[websites/linux-kde-org] content/docs: Update openQA docs for Python port, use code blocks

Git commit 012e4596541d18133bfecad3d984751bc11ade2e by Nate Graham, on behalf of Thomas Duckworth.
Committed on 06/08/2026 at 23:40.
Pushed by ngraham into branch 'master'.

Update openQA docs for Python port, use code blocks

Updates the openQA documentation to maintain its relevance now that the
developer UX has changed following the port to Python. Also ensures that
HTML code blocks are used with semantic consistency throughout.

M  +29   -17   content/docs/openqa.md

https://invent.kde.org/websites/linux-kde-org/-/commit/012e4596541d18133bfecad3d984751bc11ade2e

diff --git a/content/docs/openqa.md b/content/docs/openqa.md
index fe39ba4..05aef64 100644
--- a/content/docs/openqa.md
+++ b/content/docs/openqa.md
@@ -31,13 +31,13 @@ This makes an openQA failure a gate for image publish. Start by opening the down
 
 ### Download a staged image
 
-The link provided after the log message *“In case of failure, you can inspect and download the .iso image and sysupdate tree at…”* opens a storage browser for the build under test. Download the <code>.iso</code> there to boot it manually or give it to a local openQA stack. The <code>sysupdate</code> tree contains the staged update artifacts used by the upgrade test.
+The link provided after the log message *“In case of failure, you can inspect and download the .iso image and sysupdate tree at…”* opens a storage browser for the build under test. Download the `.iso` there to boot it manually or give it to a local openQA stack. The `sysupdate` tree contains the staged update artifacts used by the upgrade test.
 
 ### Investigate a failed job
 
 Open the job in the openQA web UI and select the failed module first. The link to the web UI will appear after the *“<name> test job is now running.”* log message. Its details include the module result, screenshots or video where applicable, and diagnostic output. In the *Logs & Assets* tab, download or view `autoinst-log.txt` for the openQA worker and test-engine log. This is the primary log for the job itself.
 
-For tests that execute commands on the system under test, KDE Linux runs them in transient systemd services and records the service journal as diagnostic output in the test result. Inspect `autoinst-log.txt` for the command output and journal. You can also download the <code>*kde-linux-collected-logs.tar.zst</code> file for logs captured by the <code>collect-logs</code> tool.
+For tests that execute commands on the system under test, KDE Linux runs them in transient systemd services and records the service journal as diagnostic output in the test result. Inspect `autoinst-log.txt` for the command output and journal. You can also download the `*kde-linux-collected-logs.tar.zst` file for logs captured by the `collect-logs` tool.
 
 ## Run tests locally
 
@@ -45,7 +45,7 @@ You can use openQA to test a locally built image before submitting a change. Thi
 
 The [KDE Linux openQA test repository](https://invent.kde.org/kde-linux/os-autoinst-distri-kdelinux) includes a local stack containing both an openQA web UI and a worker. It requires Podman and `podman-compose`, which are included in KDE Linux.
 
-Clone the test repository, then place the KDE Linux <code>.iso</code> image you want to test in its root directory. If no image is present, the test runner downloads the latest publicly available image instead.
+Clone the test repository, then place the KDE Linux `.iso` image you want to test in its root directory. If no image is present, the test runner downloads the latest publicly available image instead.
 
 Start the local stack.
 
@@ -53,32 +53,44 @@ Start the local stack.
 ./mock.sh up
 </pre>
 
-Once it is ready, open <code>http://localhost:1080</code> to inspect the openQA web UI. Jobs are not submitted automatically, so, open a shell in the container and submit the normal install and sanity-test flow.
+Once it is ready, open `http://localhost:1080` to inspect the openQA web UI. Jobs are not submitted automatically, so, open a shell in the container and submit the normal install and sanity-test flow.
 
 <pre>
 podman exec -it openqa-single-instance bash
-bash utils/jobs.sh
+./qa flow
 </pre>
 
 To run the upgrade flow instead, add <code>--upgrade</code>:
 
 <pre>
-bash utils/jobs.sh --upgrade
+./qa flow --upgrade
 </pre>
 
 To run the disk-encryption install-test flow, add <code>--encrypt</code>:
 
 <pre>
-bash utils/jobs.sh --encrypt
+./qa flow --encrypt
 </pre>
 
 You can also combine <code>--upgrade</code> and <code>--encrypt</code> options:
 
 <pre>
-bash utils/jobs.sh --upgrade --encrypt
+./qa flow --upgrade --encrypt
 </pre>
 
-The `sanity-test` job needs the `install-system` job to run first because it uses the virtual disk created by the installation. To concentrate on a particular test, adjust the submitted jobs in <code>utils/jobs.sh</code> while keeping that dependency in mind.
+The `sanity-test` job needs the `install-system` job to run first because it uses the virtual disk created by the installation. To concentrate on a particular test, adjust the submitted jobs in `lib/worker/job_flow.py` or run an individual job with <code>./qa job</code> while keeping that dependency in mind. Run <code>./qa job --help</code> to see the options it requires.
+
+For example, to run an `install-system` job where you have an `.iso` downloaded to the directory of the repository:
+
+<pre>
+./qa job \
+    --live ./kde-linux_&lt;build-id&gt;.iso \
+    --hdd kde-linux_&lt;build-id&gt;.qcow2 \
+    --sysext ./openqa-sysext.img \
+    --build &lt;build-id&gt; \
+    --name install-system \
+    --flavor live
+</pre>
 
 When you are finished, stop the stack and remove its local volumes.
 
@@ -92,12 +104,12 @@ The test definitions and the test code live in [os-autoinst-distri-kdelinux](htt
 
 Choose the test type based on what you are checking:
 
-* Use a normal Python `unittest` for command-line tools, services, filesystem state, or other non-graphical behaviour.
+* Use a normal Python <code>unittest</code> for command-line tools, services, filesystem state, or other non-graphical behaviour.
 * Use Selenium through `selenium-webdriver-at-spi` when the behaviour requires interacting with a graphical application.
 
 ### Normal Python tests
 
-Create a `unittest` in the aforementioned system extension test directory. It should make assertions about the system under test and write its results to a JUnit XML file, which will be automatically collected as an openQA asset and a GitLab CI report.
+Create a <code>unittest</code> in the aforementioned system extension test directory. It should make assertions about the system under test and write its results to a JUnit XML file, which will be automatically collected as an openQA asset and a GitLab CI report.
 
 <pre>
 import unittest
@@ -115,7 +127,7 @@ Create a matching wrapper under `tests/` that gets openQA to execute the test on
 
 <pre>
 from testapi import *
-from lib.openqa import cli_test
+from lib.test import cli_test
 
 def run(self):
     cli_test.CliTest("example").run_python()
@@ -125,7 +137,7 @@ Finally, register the wrapper in the relevant flow in `main.pm`. The wrapper col
 
 ### Graphical tests with Selenium
 
-Graphical tests are also Python `unittest` classes, but use the Appium/Selenium driver to find and interact with accessible UI elements. The Selenium runner enables the accessibility infrastructure and starts the driver for you.
+Graphical tests are also Python <code>unittest</code> classes, but use the Appium/Selenium driver to find and interact with accessible UI elements. The Selenium runner enables the accessibility infrastructure and starts the driver for you.
 
 For example, a graphical test creates a driver for its application, interacts with accessible elements, and closes the driver afterwards:
 
@@ -134,7 +146,7 @@ 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
+from lib.test import openqa_junit_xml
 
 class ExampleTests(unittest.TestCase):
     @classmethod
@@ -154,12 +166,12 @@ if __name__ == "__main__":
     openqa_junit_xml.run(ExampleTests, "example")
 </pre>
 
-Run the matching wrapper with `run_selenium()` instead of `run_python()`. Pass the installed test user for desktop applications:
+Run the matching wrapper with <code>run_selenium()</code> instead of <code>run_python()</code>. Pass the installed test user for desktop applications:
 
 <pre>
 from testapi import *
-from lib.openqa import cli_test
-from lib import user_manager
+from lib.test import cli_test
+from lib.common import user_manager
 
 def run(self):
     cli_test.CliTest("example").run_selenium(user=user_manager.installed())