nixos/tests: implement X11 for nspawn; nixos/tests/firefox*: migrate to nspawn

nixos/doc/manual/development/developing-the-test-driver.chapter.md

@@ -23,6 +23,51 @@ Beyond the test driver itself, its integration into NixOS and Nixpkgs is importa
 Finally, we have legacy entrypoints that users should move away from, but are cared for on a best effort basis.
 These include `pkgs.nixosTest`, `testing-python.nix` and `make-test-python.nix`.
 
+## Interactive display architecture {#sec-test-driver-display-architecture}
+
+QEMU owns its emulated display hardware and opens its display window directly.
+`systemd-nspawn` containers have no corresponding window, so the test driver
+uses a pipeline to present their displays during interactive test runs:
+
+```text
+machine declaration                 host presentation
+
+┌────────────────┐     ┌────────────── DisplaySession ──────────────┐
+│ display target │     │                                            │
+│ backend: X11   │────▶│ exporter ───▶ endpoint ───▶ viewer         │
+│ display: :0    │     │ X11 → VNC     vnc://…       VNC            │
+└────────────────┘     └────────────────────────────────────────────┘
+       backend selects exporter          protocol selects viewer
+```
+
+A **display target** describes a display provided by a machine. Its backend
+identifies the display technology, while backend-specific fields identify the
+display and any authentication data. Tests normally declare targets through a
+shared graphical-test module rather than selecting a presentation mechanism.
+
+A **display exporter** understands one target backend and makes that display
+available over a transport protocol. It returns a **display endpoint**, which
+contains only the protocol and the URI needed to connect. A **display viewer**
+is selected by that protocol and opens the endpoint on the host. A display
+session connects these components and owns their asynchronous startup and
+shutdown.
+
+Keeping these roles separate means that tests do not choose a transport or a
+host application. Exporters and viewers are supplied by the interactive driver
+configuration, so regular test runs neither start them nor depend on their
+packages. Multiple exporters can also reuse a viewer when they produce the
+same protocol.
+
+The current nspawn exporter starts an X11 VNC server inside the container and
+relays a host-loopback endpoint into the container's network namespace. The
+viewer remains in the host network namespace so it retains access to the
+host's graphical session. These details are private to the exporter.
+
+New display backends should fit the same boundary. For example, if an isolated
+virtual DRM/KMS device can eventually be passed to the container, a
+[ReFrame](https://github.com/AlynxZhou/reframe)-based exporter could expose its
+framebuffer over VNC without changing the VNC viewer or test configuration.
+
 ## Testing changes to the test framework {#sec-test-the-test-framework}
 
 We currently have limited unit tests for the framework itself. You may run these with `nix-build -A nixosTests.nixos-test-driver`.

nixos/doc/manual/development/running-nixos-tests-interactively.section.md

@@ -41,6 +41,34 @@ back into the test driver command line upon its completion. This allows
 you to inspect the state of the VMs after the test (e.g. to debug the
 test script).
 
+## Graphical tests {#sec-nixos-test-interactive-graphical}
+
+When a graphical host display is available, QEMU machines open their regular
+display window. For `systemd-nspawn` containers, `.driverInteractive` opens a
+VNC viewer for each X11 display declared by the test. The viewer shows the same
+display used by the test and accepts keyboard and mouse input.
+
+Because the nspawn driver must run as root, preserve the host graphical-session
+variables when starting it. For X11, use:
+
+```ShellSession
+$ sudo --preserve-env=DISPLAY,XAUTHORITY \
+    ./result/bin/nixos-test-driver
+```
+
+For Wayland, use:
+
+```ShellSession
+$ sudo --preserve-env=WAYLAND_DISPLAY,XDG_RUNTIME_DIR \
+    ./result/bin/nixos-test-driver
+```
+
+If neither `DISPLAY` nor `WAYLAND_DISPLAY` is set, the driver does not open
+graphical viewers.
+
+See the [interactive display architecture](#sec-test-driver-display-architecture)
+for how display targets, exporters, and viewers are connected.
+
 ## Shell access to VMs in interactive mode {#sec-nixos-test-shell-access}
 
 ::: {.warning}

nixos/doc/manual/development/writing-nixos-tests.section.md

@@ -144,12 +144,16 @@ Some advantages of virtual machines over containers are:
 
 - Virtual machines run a separate kernel, which allows testing kernel features
   (kernel modules, etc.).
-- Virtual machines support testing graphical applications on X11.
 - Virtual machines allow testing NixOS modules that use systemd's namespacing options (such as `ProtectSystem=` or `MountAPIVFS=`).
 - Virtual machines allow testing [`specialisation`](options.html#opt-specialisation).
   (Switching to a specialisation requires the creation of SUID/SGID wrappers, which is disallowed in `systemd-nspawn` within the Nix sandbox.)
 - Virtual machines allow the execution of `setuid` binaries.
 
+Both backends support testing graphical applications on X11. Virtual machines
+provide emulated display hardware, while containers use a headless X server.
+See [running tests interactively](#sec-running-nixos-tests-interactively) for how
+their displays are presented during debugging.
+
 Refer to the sections on [QEMU virtual machines](#ssec-nixos-test-qemu-vms)
 and [systemd-nspawn containers](#ssec-nixos-test-nspawn-containers) below
 for more details on configuring each type of machine.

nixos/doc/manual/redirects.json

@@ -2420,6 +2420,9 @@
   "sec-running-nixos-tests-interactively": [
     "index.html#sec-running-nixos-tests-interactively"
   ],
+  "sec-nixos-test-interactive-graphical": [
+    "index.html#sec-nixos-test-interactive-graphical"
+  ],
   "sec-nixos-test-shell-access": [
     "index.html#sec-nixos-test-shell-access"
   ],
@@ -2447,6 +2450,9 @@
   "chap-developing-the-test-driver": [
     "index.html#chap-developing-the-test-driver"
   ],
+  "sec-test-driver-display-architecture": [
+    "index.html#sec-test-driver-display-architecture"
+  ],
   "sec-test-the-test-framework": [
     "index.html#sec-test-the-test-framework"
   ],

nixos/doc/manual/release-notes/rl-2611.section.md

@@ -257,6 +257,8 @@
 
 - The `shell_interact()` function on interactive runs of NixOS VM tests has been deprecated. Use the SSH backdoor instead.
 
+- NixOS tests using `systemd-nspawn` containers now support graphical X11 applications, including window queries, screenshots, and OCR. The [interactive test driver](#sec-running-nixos-tests-interactively) opens each container display in a VNC viewer for observation and input.
+
 - NixOS VM tests now prefer to express durations and timeouts as `datetime.timedelta` values instead of bare numbers. Methods such as `machine.wait_until_succeeds`, `machine.sleep`, `retry`, and `polling_condition` now accept a `timedelta` (e.g., `machine.wait_for_unit("sshd.service", timeout=datetime.timedelta(minutes=1))`). Passing an `int`/`float` as seconds still works but now emits a deprecation warning. Argument names that explicitly defined units were preserved but have had `timedelta` equivalents introduced (`timeout_seconds` → `timeout`, `secs` → `duration`, `seconds_interval` → `interval`).
 
 - `darwin.linux-builder-vz` has been added: a variant of `darwin.linux-builder` that runs the builder guest on Apple's Virtualization.framework via the new `vzvm` package, translating `x86_64-linux` builds with Rosetta instead of emulating them. Apple silicon hosts only. As part of this, the `nixos/modules/profiles/nix-builder-vm.nix` profile has been split into the backend-neutral `nixos/modules/profiles/nix-builder.nix` and a QEMU-specific part. Existing imports of `nix-builder-vm.nix` keep working unchanged.

nixos/lib/test-driver/src/test_driver/__init__.py

@@ -9,8 +9,9 @@
 import ptpython.repl
 from colorama import Fore, Style
 
+from test_driver.config import load_driver_configuration
 from test_driver.debug import Debug, DebugAbstract, DebugNop
-from test_driver.driver import Driver, load_driver_configuration
+from test_driver.driver import Driver
 from test_driver.logger import (
     CompositeLogger,
     JunitXMLLogger,
@@ -178,6 +179,7 @@ def main() -> None:
         logger=logger,
         keep_machine_state=args.keep_machine_state,
         debug=debugger,
+        interactive=bool(args.interactive),
     ) as driver:
         if driver.config.enable_ssh_backdoor:
             driver.dump_machine_ssh()

nixos/lib/test-driver/src/test_driver/config.py

@@ -0,0 +1,69 @@
+import datetime as dt
+import json
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+DisplayBackend = Literal["x11"]
+DisplayProtocol = Literal["vnc"]
+
+
+class X11DisplayTargetConfiguration(BaseModel):
+    backend: DisplayBackend
+    display: str = ":0"
+    xauthority: Path = Path("/root/.Xauthority")
+
+
+DisplayTargetConfiguration = X11DisplayTargetConfiguration
+
+
+class VncDisplayViewerConfiguration(BaseModel):
+    kind: Literal["vnc"]
+    executable: Path
+
+
+DisplayViewerConfiguration = VncDisplayViewerConfiguration
+
+
+class NspawnX11VncExporterConfiguration(BaseModel):
+    kind: Literal["x11-vnc"]
+    server: Path
+    relay: Path
+
+
+NspawnDisplayExporterConfiguration = NspawnX11VncExporterConfiguration
+
+
+class MachineConfiguration(BaseModel):
+    name: str
+    start_script: Path
+
+
+class QemuMachineConfiguration(MachineConfiguration):
+    pass
+
+
+class NspawnMachineConfiguration(MachineConfiguration):
+    display_targets: list[DisplayTargetConfiguration] = Field(default_factory=list)
+    display_exporters: dict[DisplayBackend, NspawnDisplayExporterConfiguration] = Field(
+        default_factory=dict
+    )
+
+
+class DriverConfiguration(BaseModel):
+    vms: dict[str, QemuMachineConfiguration]
+    containers: dict[str, NspawnMachineConfiguration]
+    display_viewers: dict[DisplayProtocol, DisplayViewerConfiguration] = Field(
+        default_factory=dict
+    )
+    vlans: list[int]
+    global_timeout: dt.timedelta
+    enable_ssh_backdoor: bool
+    test_script: Path
+
+
+def load_driver_configuration(file_path: str) -> DriverConfiguration:
+    with open(file_path) as file:
+        data = json.load(file)
+    return DriverConfiguration.model_validate(data)