openQA para desarrolladores y mantenedores
KDE Linux usa openQA to automatically para probar automáticamente cada imagen del sistema antes de publicarla. openQA arranca cada imagen en una máquina virtual y comprueba que se puede instalar, actualizar y usar de forma correcta.
openQA usa cierta terminología: un trabajo es una ejecución de un paquete de pruebas sobre una imagen, mientras que un trabajador es la máquina o el contenedor que ejecuta el trabajo. La documentación de openQA explica estos y otros conceptos, incluidos los módulos de pruebas, los grupos de trabajo, activos y la interfaz web.
Cómo funcionan las pruebas
El trabajador de la prueba se ejecuta junto con la canalización de integración continua (CI), lo que le permite usar las imágenes y los discos virtuales generados durante la compilación sin tener que subir esos archivos grandes a otro lugar. Las pruebas se envían a la máquina virtual mediante una extensión del sistema y se comunican con ella a través de SSH.
Las pruebas de escritorio usan la API de accesibilidad a través de selenium-webdriver-at-spi, lo que les permite interactuar con las aplicaciones y comprobar su estado sin depender únicamente de la comparación de capturas de pantalla. El conjunto de pruebas también verifica si hay servicios del sistema con fallos, procesos de escritorio bloqueados, problemas de red y regresiones en las órdenes de KDE Linux.
Flujo de trabajo del mantenedor y de la canalización de CI
En la rama predeterminada protegida del repositorio principal de KDE Linux, la canalización funciona de la siguiente manera:
- El trabajo imaging compila, firma y prepara la imagen y su canal sysupdate en
storage.kde.org. - El trabajo trigger-openqa inicia la canalización en os-autoinst-distri-kdelinux, pasándole la URL de la imagen preparada y la URL del canal sysupdate.
- La canalización de descarga ejecuta los flujos
installyupgradedeclarados entests/tests.toml, cada uno de ellos con instalaciones planas y cifradas. - El trabajo publish principal se ejecuta solo después de que la canalización de openQA haya finalizado correctamente. Su función es promocionar la imagen ya preparada para su consumo público.
Esto convierte un fallo de openQA en un obstáculo para la publicación de la imagen. Para empezar, abre la canalización descendente del trabajo trigger-openqa y, a continuación, abre el trabajo de openQA que ha fallado desde su registro de CI. La página del trabajo muestra los módulos de prueba en orden y permite identificar si el fallo se produce durante la instalación, las pruebas de integridad del sistema instalado o la ruta de actualización.
Descargar una imagen preparada
El enlace que se proporciona tras el mensaje de registro «En caso de fallo, inspecciona y descarga la imagen y el árbol sysupdate en…», abre un explorador de almacenamiento para la compilación bajo prueba. Descarga la .iso ahí para arrancarla manualmente o proporciónasela a una pila openQA local. El árbol sysupdate contiene los artefactos de actualización preparados que usa la prueba de actualización.
Investigar un trabajo que ha fallado
Abre el trabajo en la interfaz web de openQA y selecciona primero el módulo que ha fallado. El enlace a la interfaz web aparecerá tras el mensaje del registro «El trabajo de prueba autoinst-log.txt del trabajador openQA y el registro «test-engine». Este es el registro principal para el propio trabajo.
Para las pruebas que ejecutan órdenes en el sistema bajo prueba, KDE Linux las ejecuta en servicios systemd transitorios y graba el diario del servicio como salida de diagnóstico en el resultado de la prueba. Inspecciona el autoinst-log.txt de la salida de la orden y el diario. También puedes descargar el archivo *kde-linux-collected-logs.tar.zst para los registros capturados por la herramienta collect-logs.
Ejecutar pruebas localmente
Puedes usar openQA para probar una imagen compilada localmente antes de enviar un cambio. Esto es necesario cuando se trabaja con una bifurcación fuera de kde-linux/kde-linux: su canalización de CI crea una imagen de prueba, pero no lanza la canalización openQA. También es útil cuando se desarrollan pruebas para los cambios propios.
El repositorio de pruebas openQA de KDE Linux incluye una pila local que contiene tanto una interfaz web de openQA como un trabajador. Requiere Python 3.14, Podman y podman-compose, que se incluyen en KDE Linux.
Clona el repositorio de pruebas y luego sitúa la imagen .iso de KDE Linux que quieras probar en su directorio raíz. Si no hay ninguna imagen presente, el lanzador de la prueba descarga la última imagen disponible públicamente.
Inicia la pila local desde la raíz del repositorio.
./qa-mock up
Cuando esté preparada, abre http://localhost:1080 para inspeccionar la interfaz web de openQA. Los trabajos no se envían de forma automática, por lo que debes abrir un intérprete en el contenedor y enviar el flujo install. Ejecuta las órdenes flow, job y build-sysext dentro de este contenedor.
./qa-mock enter ./qa flow install
Para ejecutar el flujo upgrade:
./qa flow upgrade
Para una instalación cifrada, pasa FDE_INSTALL=1 como ajuste de openQA. El sufijo de sabor distingue los trabajos cifrados en la interfaz web:
./qa flow install --var FDE_INSTALL=1 --flavor-suffix=-encrypted ./qa flow upgrade --var FDE_INSTALL=1 --flavor-suffix=-encrypted
--var NOMBRE=VALOR se puede repetir, aunque cada variable se debe declarar en la lista de variables del flujo seleccionado en tests/tests.toml.
El paquete sanity-test usa el disco virtual creado por install-system. Para concentrarte en determinadas pruebas, edita la lista tests del paquete en tests/tests.toml o declara otro paquete y flujo ahí. También puedes ejecutar un paquete individual con ./qa job --name <paquete> mientras tienes en cuenta sus dependencias de disco. Las órdenes flow, job y build-sysext aceptan --manifest-path <ruta> para usar un manifiesto distinto de tests/tests.toml. Las rutas de las pruebas dentro del manifiesto son relativas al directorio del manifiesto. Ejecuta ./qa job --help para obtener ayuda sobre las opciones que necesita.
Por ejemplo, compila la extensión del sistema y ejecuta un trabajo install-system con una .iso del directorio del repositorio. Sustituye la ID y la variante de la compilación con las de tu imagen:
./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
Cuando hayas terminado, sal de la shell del contenedor, detén la pila y elimina sus volúmenes locales de la máquina.
./qa-mock down -v
./qa-mock pasa argumentos a podman-compose. Por ejemplo, usa ./qa-mock up -d para iniciar la pila en segundo plano.
Probar actualizaciones entre compilaciones locales
Coloca la ISO base en la raíz del repositorio de prueba. Cuando inicies la pila desde la máquina, define KDE_LINUX_OUTPUT al directorio de mkosi.output que contenga la compilación a la que te quieras actualizar.
KDE_LINUX_OUTPUT=~/Repositories/kde-linux/mkosi.output ./qa-mock up
Entra en el contenedor y ejecuta el flujo de actualización, sustituyendo <build-id> con la ID de la compilación de la ISO base:
./qa-mock enter
./qa flow upgrade \
--upgrade-from /casedir/kde-linux_<build-id>.iso \
--upgrade-to /kde-linux-output
Ambas opciones se deben indicar de forma conjunta. El repositorio se monta en /casedir, y el directorio de mkosi.output seleccionado se monta como solo lectura en /kde-linux-output. La compilación más reciente de este directorio se sirve a la máquina virtual como fuente temporal para sysupdate y debe ser más reciente que la ISO base. Añade --var FDE_INSTALL=1 --flavor-suffix=-encrypted para probar una instalación cifrada.
Declarar paquetes y flujos
tests/tests.toml define la distribución (name y distri), los paquetes y los flujos. Un paquete es una lista ordenada de pruebas que se ejecuta en un trabajo de openQA. Su action determina el uso que hace el trabajo del disco virtual:
installarranca la imagen live y crea el disco instalado.upgradearranca el disco instalado y defineDO_UPGRADEpara las pruebas que realizan la actualización.testarranca el disco instalado para validación.
Un flujo ejecuta los paquetes en el orden declarado, pasando el disco instalado entre trabajos. KDE Linux define estos flujos:
[flows.install] suites = ["install-system", "sanity-test"] variables = ["FDE_INSTALL"] [flows.upgrade] suites = ["install-system", "upgrade-system", "sanity-test"] variables = ["FDE_INSTALL"]
El flujo install instala y comprueba la compilación que se está probando. El flujo upgrade instala primero una imagen anterior, la actualiza a la compilación que se está probando y ejecuta las pruebas para determinar su estado. Para una compilación de CI por etapas, la base es la última imagen publicada. Sin --upgrade-from ni --upgrade-to, una ejecución de actualización local usará por defecto la última compilación pública como destino, usando una ISO local anterior si está disponible o descargando la imagen anterior.
Antes de cada tarea, el trabajador genera un directorio de pruebas temporal (CASEDIR) con una planificación de ejecución main.pm para el paquete de pruebas seleccionado. Las pruebas se ejecutan en el orden del manifiesto, incluyendo las entradas repetidas. Edita el manifiesto para modificar la planificación de ejecución.
Escribir una prueba
Las definiciones de la prueba y el código residen en os-autoinst-distri-kdelinux. Añade guiones de prueba en tests/ junto a las pruebas relacionadas y regístralos en el correspondiente array tests de tests/tests.toml. Por ejemplo:
[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 },
]
Las pruebas openqa se ejecutan en el trabajador y usan directamente las API de openQA. Las pruebas python y selenium se ejecutan en el sistema bajo prueba, la extensión del sistema empaqueta automáticamente sus guiones y el trabajador genera los adaptadores de prueba de openQA que los invocan.
Escoge el tipo de prueba según lo que quieras comprobar:
- Usa una
unittestnormal de Python para herramientas de la línea de órdenes, servicios, estado de sistemas de archivos u otro comportamiento no gráfico. - Usa Selenium mediante
selenium-webdriver-at-spicuando el comportamiento requiera interactuar con una aplicación gráfica.
Pruebas normales de Python
Crea una unittest en tests/ como, por ejemplo, tests/kdelinux/system/example.py. Esta prueba debe realizar aserciones sobre el sistema bajo prueba y escribir sus resultados en un archivo XML de JUnit, que se recopilará automáticamente como un activo de openQA y un informe de 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")
Añade una entrada al array tests del paquete correspondiente:
{ path = "kdelinux/system/example.py", type = "python" },
El adaptador generado recopila el resultado de JUnit y la salida de la orden, de modo que los fallos aparezcan en el trabajo openQA y en los artefactos CI.
Pruebas gráficas con Selenium
Las pruebas gráficas también son clases unittest de Python, pero usan el controlador de Appium/Selenium para encontrar elementos accesibles de la interfaz de usuario e interactuar con ellos. El lanzador de Selenium activa la infraestructura de accesibilidad e inicia el controlador automáticamente.
Por ejemplo, una prueba gráfica crea un controlador para su aplicación, interactúa con los elementos accesibles y cierra el controlador después:
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")
Guarda el guion como, por ejemplo, tests/kdelinux/app/example.py y añádelo al paquete relevante con type = "selenium". Selecciona el usuario de prueba instalado para las aplicaciones de escritorio:
{ path = "kdelinux/app/example.py", type = "selenium", user = "installed", timeout = 180 },
Ejecuta el flujo que contiene tu paquete localmente mientras lo desarrollas.
Opciones de la prueba y adaptadores personalizados
Para los adaptadores SUT generados, las entradas del manifiesto pueden definir user (root, live, installed o plasma_setup), timeout en segundos (90 de forma predeterminada), artifacts como una lista de rutas a recoger, y los indicadores de openQA fatal = true o always_run = true. Define enabled = false para dejar una prueba declarada aunque excluida de la planificación.
Cuando una prueba necesita algún tipo de orquestación personalizada para ejecutarse, coloca un adaptador junto a su guion SUT y apunta a él con override:
{ path = "kdelinux/system/collect_logs.py", type = "selenium", override = "kdelinux/system/collect_logs.openqa.py" },
Este adaptador personalizado es responsable de su recopilación de indicadores, user, timeout y artifact, y debe pasar la ruta relativa del guion SUT a CliTest.run_python() o a CliTest.run_selenium(). Consulta el archivo collect_logs.openqa.py existente para ver un ejemplo.
Para más información sobre la escritura de pruebas con Selenium, consulta Pruebas de automatización de Appium y Pruebas de la interfaz gráfica con selenium-webdriver-at-spi.
Saber más
Para una explicación más detallada sobre la prueba y su implementación, consulta Pruebas openQA en KDE Linux. El desarrollo de la infraestructura de pruebas se lleva a cabo en el repositorio os-autoinst-distri-kdelinux.
Artículo escrito por Thomas Duckworth bajo las condiciones de la licencia CC-BY-4.0.