Headless QGIS and WebEngine qualification

The smoke-marked pytest tests cover the headless path QGIS uses to host a QWebEngineView, the scheduler, native services, and Desktop lifecycle probes. They are excluded from the normal suite and require a real QGIS installation. Run all seven explicitly with:

pixi run -e default pytest -c packages/qgis-sdk-python/pyproject.toml packages/qgis-sdk-python/tests -m smoke -v -s

Each probe is isolated from the others so QGIS and Chromium can initialize and shut down safely. Pytest assertions determine success; -s shows the diagnostic evidence. To run just the WebEngine test:

pixi run -e default pytest -c packages/qgis-sdk-python/pyproject.toml packages/qgis-sdk-python/tests/scripts/test_qualification_webengine.py -m smoke -s

Example evidence from an earlier run:

{
  "chromium_version": "140.0.0.0",
  "error": null,
  "load_finished": true,
  "platform": "Linux-6.1.158+-x86_64-with-glibc2.36",
  "python_version": "3.14.8",
  "qgis_exited": true,
  "qgis_initialised": true,
  "qgis_version": "4.2.3-Belém do Pará",
  "qt_version": "6.11.2",
  "qualified": true,
  "webengine_available": true
}

The harness resolves everything it needs from the active prefix, so the same command works in any environment that provides a QGIS installation. It sets QT_QPA_PLATFORM=offscreen, the Chromium flags --no-sandbox --disable-gpu --disable-dev-shm-usage --single-process, the PROJ_LIB and QGIS_PREFIX_PATH of that prefix, and puts the QGIS Python bindings on PYTHONPATH.

The support promise itself is one machine-readable source, qgis_sdk_tools.targets (TASK-9 AC 2, decision-37): qgis-sdk targets prints it, doc-12 renders it, tests/test_targets_native.py fails when the host the native suite runs on is not a qualified row, and the release workflow records it in the job summary. The table below is the per-requirement evidence behind those rows.

Requirement	Linux (`linux-64`)	macOS (`macos-latest` arm64)	Windows (`windows-latest` x86-64)
TypeScript bridge (`packages/qgis-sdk-typescript`)	Qualified (Bun 1.4.2, 95 tests, 100% cov)	Qualified in CI (Bun 1.4.2, 95 tests)	Qualified in CI (Bun 1.4.2, 95 tests)
QGIS with Python bindings	Qualified (Pixi `default`, QGIS 4.2.3)	Blocker: no macOS QGIS 4 prefix in CI/sandbox (TASK-33 AC #1)	Blocker: no Windows QGIS 4 prefix in CI/sandbox (TASK-33 AC #1)
Qt WebEngine Python bindings (`pyqt6-webengine` 6.11.0)	Qualified headless (`offscreen`, Chromium 140.0.0.0)	Blocker: requires macOS QGIS/Qt prefix	Blocker: requires Windows QGIS/Qt prefix
Headless QGIS Desktop plugin manager (`qgis --noplugins --code`)	Qualified (scaffold and adapter smoke tests)	Blocker: requires macOS QGIS Desktop binary	Blocker: requires Windows QGIS Desktop binary
QGIS network transport (`NativeNetworkTransport`: proxy, auth database, certificate trust, redirects, body ceiling)	Qualified headless against loopback servers (`tests/test_network_native.py`, 25 tests; limits from `network_limits_probe.py`)	Blocker: requires macOS QGIS/Qt prefix	Blocker: requires Windows QGIS/Qt prefix
Display-server Desktop GUI + in-Desktop `QWebEngineView` rendering	Blocker: no display server or `Xvfb` in sandbox/CI (`offscreen` renders no widgets, TASK-33 AC #2)	Blocker: no interactive display session in CI (TASK-33 AC #2)	Blocker: no interactive display session in CI (TASK-33 AC #2)
Chromium sandbox	Disabled by headless flags above	N/A	N/A

Without the Chromium flags the WebEngine process fails with eglInitialize: Failed to get system egl display. ANGLE, EGL, dbus and PDAL messages printed during a run are noise and do not affect the result.

tests/scripts/test_qualification_webengine.py covers the harness helpers in the QGIS-free suite. The end-to-end run is opt-in, because it needs a real QGIS installation:

pixi run -e default pytest -c packages/qgis-sdk-python/pyproject.toml packages/qgis-sdk-python/tests/scripts/test_qualification_webengine.py -m smoke -s

The headless path is not a visible Desktop GUI qualification and does not claim universal QGIS 4 support: the Linux sandbox and CI runners have no display server or Xvfb, and pixi.toml locks linux-64 only, so no Windows or macOS QGIS 4 installation has been tested. qgis_sdk.adapters.webengine therefore only proves that the optional bindings can be located on a qualified host and that a missing installation is reported with an actionable error.