openQA per a desenvolupadors i mantenidors

La KDE Linux utilitza openQA per a provar automàticament totes les imatges del sistema abans de publicar-les. openQA arranca cada imatge en una màquina virtual i comprova que es pot instal·lar, actualitzar i utilitzar correctament.

openQA té una terminologia específica: un treball és una execució d'un conjunt de proves d'una imatge, mentre que un treballador és la màquina o contenidor que executa el treball. La documentació d'OpenQA explica estos i altres conceptes, inclosos els mòduls de prova, grups de treball, actius i la interfície d'usuari web.

Com funcionen les proves

El treballador de la prova s'executa junt amb la canonada de CI, de manera que pot utilitzar les imatges i els discs virtuals produïts per la construcció sense carregar estos fitxers grans en un altre lloc. Les proves se subministren a la màquina virtual a través d'una extensió del sistema i es comuniquen amb ella a través de SSH.

Les proves d'escriptori utilitzen l'API d'accessibilitat a través de selenium-webdriver-at-spi, permetent-les interactuar amb les aplicacions i comprovar el seu estat sense dependre únicament de la coincidència de captures de pantalla. El conjunt també comprova si hi ha serveis del sistema que hagen fallat, processos d'escriptori que petin, problemes de xarxa i regressions a les ordres de la KDE Linux.

Canonada de CI i flux de treball del mantenidor

En la branca predeterminada protegida de la font principal del repositori de la KDE Linux, la canonada funciona de la manera següent:

  1. El treball de creació d'imatges construïx, signa i situa la imatge i el seu canal «sysupdate» en storage.kde.org.
  2. El treball trigger-openqa inicia la canonada en os-autoinst-distri-kdelinux, passant-hi l'URL de la imatge situada i l'URL del canal «sysupdate».
  3. La canonada de la font secundària executa els fluxos install i upgrade declarats a tests/tests.toml, cada un amb instal·lació normal i encriptada.
  4. El treball de publicació de la font principal només s'executarà després que el pipeline openQA haja tingut èxit. Promou la imatge ja posada en escena per al consum públic.

Açò fa que una fallada d'openQA siga una porta per a la publicació d'imatges. Comenceu obrint la canonada de la font secundària des del treball trigger-openqa, i després obriu el treball openQA que ha fallat des del seu registre de CI. La pàgina de treball mostra els mòduls de prova en ordre i us permet identificar si la fallada està en la instal·lació, les proves de sanejament del sistema instal·lat o el camí d'actualització.

Baixada d'una imatge situada

L'enllaç proporcionat després del missatge de registre «En cas de fallada, inspeccioneu i descarregueu la imatge i l'arbre de sysupdate a…» obre un navegador d'emmagatzematge per a la construcció que es prova. Descarregueu allí la .iso per arrencar-la manualment o donar-la a una pila local d'openQA. L'arbre del sysupdate conté els artificis d'actualització «staged» utilitzats per la prova d'actualització.

Investigació d'un treball que ha fallat

Obriu el treball a la interfície d'usuari web d'OpenQA i trieu primer el mòdul que ha fallat. L'enllaç cap a la interfície d'usuari web apareixerà després del missatge de registre « test job is now running.». Els seus detalls inclouen el resultat del mòdul, captures de pantalla o vídeo, si escau, i l'eixida de diagnòstic. En la pestanya Registres i actius, descarregueu o visualitzeu autoinst-log.txt per al treballador d'openQA i el registre del motor de proves. Este és el registre principal del treball en si.

Les proves que executen ordres en el sistema per a proves, la KDE Linux les executa en serveis de «systemd» transitoris i registra el diari de servei com a eixida de diagnòstic en el resultat de la prova. Inspeccioneu autoinst-log.txt on hi ha l'eixida d'ordres i el diari. També podeu baixar el fitxer *kde-linux-collected-logs.tar.zst dels registres capturats per l'eina collect-logs.

Executar localment les proves

Podeu utilitzar openQA per a provar una imatge construïda localment abans d'enviar un canvi. Açò és necessari quan es treballa des d'una bifurcació fora de kde-linux/kde-linux: la seua canonada de CI construïx una imatge de prova, però no activa la canonada d'openQA. També és útil mentre desenvolupeu proves per als vostres propis canvis.

El repositori de proves d'openQA de KDE Linux inclou una pila local que conté tant una interfície d'usuari web d'openQA i un treballador. Requereix Python 3.14, Podman i podman-compose, que estan inclosos a KDE Linux.

Cloneu el repositori de proves, després col·loqueu la imatge .iso de la KDE Linux que voleu provar al seu directori arrel. Si no hi ha cap imatge, l'executor de proves baixa l'última imatge disponible públicament.

Inicieu la pila local a partir de l'arrel del repositori:

./qa-mock up

Un cop estigui llest, obriu http://localhost:1080 per inspeccionar la interfície d'usuari web d'openQA. Els treballs no s'envien automàticament, per tant, obriu un intèrpret d'ordres al contenidor i envieu el flux install. Executeu les ordres flow, job i build-sysext dins d'aquest contenidor.

./qa-mock enter
./qa flow install

En canvi, per a executar el flux upgrade:

./qa flow upgrade

Per a una instal·lació encriptada, passeu FDE_INSTALL=1 com un paràmetre d'openQA. El sufix «flavor» distingeix els treballs encriptats a la interfície d'usuari web:

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

Es pot repetir --var NAME=VALUE, però cada variable cal que estigui declarada a la llista de variables del flux seleccionat a tests/tests.toml.

El conjunt sanity-test utilitza el disc virtual creat per install-system. Per a concentrar-se en proves particulars, editeu la llista tests del conjunt a tests/tests.toml, o declareu allí un altre conjunt i flux. També podeu executar un conjunt individual amb ./qa job --name <suite> mentre es tenen en compte les seves dependències de disc. Les ordres flow, job i build-sysext accepten --manifest-path <path> per a utilitzar un manifest diferent al de tests/tests.toml. Els camins de prova dins del manifest són relatius al directori del manifest. Executeu ./qa job --help per a les seves opcions requerides.

Per example, construeix l'extensió del sistema i executa un treball install-system amb una .iso al directori del repositori. Substitueix l'ID de construcció i la variant per les de la vostra imatge:

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

Quan hàgiu acabat, sortiu de l'intèrpret d'ordres del contenidor, atureu la pila i elimineu els seus volums locals des de l'amfitrió.

./qa-mock down -v

./qa-mock passa els arguments a podman-compose. Per exemple, useu ./qa-mock up -d per a iniciar la pila en segon pla.

Prova d'actualitzacions entre construccions locals

Situeu la ISO base a l'arrel del repositori de proves. En iniciar la pila des de l'amfitrió, definiu KDE_LINUX_OUTPUT al directori mkosi.output que conté la construcció a la qual voleu actualitzar:

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

Introduïu el contenidor i executeu el flux d'actualització, reemplaçant &lt;build-id&gt; amb l'ID de construcció de la ISO base:

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

Totes dues opcions han d'oferir-se conjuntament. El repositori està muntat a /casedir, i el directori seleccionat mkosi.output està muntat només de lectura a /kde-linux-output. La construcció més nova d'aquest directori se serveix a la màquina virtual com una font temporal de «sysupdate» i ha de ser més nova que la ISO base. Afegiu --var FDE_INSTALL=1 --flavor-suffix=-encrypted per provar una instal·lació encriptada.

Declaració de conjunts i fluxos

tests/tests.toml defineix la distribució (name i distri), conjunts i fluxos. Un conjunt és una llista ordenada de proves que s'executaran en un treball d'openQA job. La seva action determina com el treball utilitza el disc virtual:

  • install arrenca la imatge en viu i crea el disc instal·lat.
  • upgrade arrenca el disc instal·lat i estableix DO_UPGRADE per a les proves que portin a terme l'actualització.
  • test arrenca el disc instal·lat i per a la validació.

Un flux executa els conjunts en l'ordre declarat, passant el disc instal·lat entre els treballs. KDE Linux defineix aquests fluxos:

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

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

El flux install instal·la i comprova la construcció sota prova. El flux upgrade primer instal·la una imatge antiga, l'actualitza a la construcció sota prova i després executa proves de sanejament. Per a una construcció CI «staged», la base és la darrera imatge publicada. Sense --upgrade-from ni --upgrade-to, s'executarà de manera predeterminada una actualització local a la darrera construcció pública com a objectiu, utilitzant una ISO local més antiga si n'hi ha una disponible o descarregant la imatge anterior.

Abans de cada treball, el treballador genera un directori de proves temporal (CASEDIR) amb una planificació main.pm per al conjunt seleccionat. Les proves s'executen en l'ordre del manifest, incloses les entrades repetides. Editeu el manifest per a canviar la planificació.

Escriure una prova

Les definicions de prova i el codi estan a os-autoinst-distri-kdelinux. Afegiu els scripts de prova dins de tests/, junt amb les proves relacionades i registreu-los a la matriu test del paquet apropiat a tests/tests.toml. Per exemple:

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

Les proves openqa s'executen al treballador i utilitzen les API d'openQA directament. Les proves python i selenium s'executen en el sistema sota prova, l'extensió del sistema empaqueta els seus scripts automàticament i el treballador genera els embolcalls de prova openQA que els invoquen.

Trieu el tipus de prova en funció del que esteu comprovant:

  • Utilitzeu un unittest normal de Python per a eines de línia d'ordres, serveis, estat del sistema de fitxers o altres comportaments no gràfics.
  • Utilitzeu Selenium a través de selenium-webdriver-at-spi quan el comportament requerix interactuar amb una aplicació gràfica.

Proves normals de Python

Creeu una unittest dins de tests/, per exemple tests/kdelinux/system/example.py. Ha de fer assercions sobre el sistema a provar i escriure els seus resultats a un fitxer XML de JUnit, que es recollirà automàticament com un actiu d'openQA i un informe 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")

Afegiu una entrada a la matriu tests del conjunt implicat:

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

L'embolcall generat recull el resultat de JUnit i la sortida de l'ordre de manera que les fallades apareixen en el treball d'openQA i els artificis de CI.

Proves gràfiques amb Selenium

Les proves gràfiques també són classes unittest de Python, però utilitzen el controlador Appium/Selenium per a trobar i interactuar amb elements accessibles de la interfície d'usuari. L'executor de Selenium habilita la infraestructura d'accessibilitat i inicia el conductor per a tu.

Per exemple, una prova gràfica crea un controlador per a la seua aplicació, interactua amb els elements accessibles i després tanca el controlador:

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

Deseu l'script com, per exemple, tests/kdelinux/app/example.py, i afegiu-lo al conjunt implicat amb type = "selenium". Seleccioneu l'usuari de prova instal·lat per a les aplicacions d'escriptori:

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

Executeu el flux que conté el vostre paquet localment mentre el desenvolupeu.

Opcions de prova i embolcalls personalitzats

Per als embolcalls SUT generats, les entrades del manifest poden establir user (root, live, installed o plasma_setup), timeout en segons (predeterminat a 90), artifacts com a una llista de camins a recollir i els indicadors d'openQA fatal = true o always_run = true. Establiu enabled = false per a deixar una prova declarada mentre l'excloeu de la planificació.

Quan una prova necessita algun tipus d'orquestració personalitzada a executar, poseu un embolcall al costat del seu script SUT i apunteu-hi amb override:

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

Aquest embolcall personalitzat es responsable dels seus indicadors, usuari, temps d'expiració i recol·lecció d'artefactes, i cal que passi el camí relatiu de l'script SUT a CliTest.run_python() o CliTest.run_selenium(). Vegeu el collect_logs.openqa.py existent com a exemple.

Per a més informació sobre l'escriptura de proves de Selenium, vegeu Proves d'automatització d'Appium i Proves GUI amb selenium-webdriver-at-spi.

Aprendre'n més

Per a una explicació més detallada del flux de proves i la seua implementació, vegeu proves d'openQA en la KDE Linux. La infraestructura de proves es desenvolupa al repositori os-autoinst-distri-kdelinux.

Article escrit per d'acord amb la llicència CC-BY-4.0.