Integrate Spix UI test automation library

[magnesj]

Context

ResInsight currently has no in-process hook for driving the QtWidgets UI from external test scripts. gRPC + the rips Python package give scripted control over the data model, but cannot click menus, push buttons, or read widget state.

Spix (MIT) is a minimally invasive Qt UI test automation library. It runs an HTTP/AnyRPC server inside the application process and lets external scripts (Python, curl, etc.) issue mouseClick("mainWindow/ok_button")-style commands against the live widget tree. Spix supports QtWidgets on Qt 6 (the SPIX_BUILD_QTWIDGETS option, introduced in 0.6).

Goal: opt-in build flag RESINSIGHT_ENABLE_SPIX that links Spix into ResInsight, starts an AnyRpcServer when --spix-port <n> is passed on the command line, and ships a tiny example Python test demonstrating the workflow.

Decisions:

• Source: FetchContent (Spix v0.14) + vcpkg (anyrpc). Initially planned to take Spix via vcpkg too, but the vcpkg spix port pulls in qtbase and qtdeclarative as transitive deps which would force a duplicate Qt6 build alongside the project's existing system Qt6. Pivoted to fetching Spix as source so it builds against the project Qt6 and only anyrpc flows through vcpkg.
• Scope: RPC server + one example test.
• Gating: RESINSIGHT_ENABLE_SPIX CMake option, OFF by default.
• Pinned Spix tag: v0.14 (commit a9c9bb178f). Pinning chosen deliberately — see prior comment about Qt 6.5 inputMethodHints regression that required bisecting Spix versions.

Steps

• 1. Add anyrpc to vcpkg.json. (Initially added spix here too; later removed in favour of FetchContent.)
• 2. Add RESINSIGHT_ENABLE_SPIX CMake option in CMakeLists.txt, fetch Spix via FetchContent at v0.14 with SPIX_BUILD_QTWIDGETS=ON / SPIX_BUILD_QTQUICK=OFF / SPIX_BUILD_EXAMPLES=OFF, and link Spix::QtWidgets PUBLIC into ApplicationLibCode (since RiaGuiApplication.cpp lives there; ResInsight.exe picks it up transitively).
• 3. Register --spix-port CLI option in RiaArgumentParser.cpp.
• 4. Start/stop Spix server in RiaGuiApplication (header forward-decls + members, cpp handleArguments + destructor), gated on ENABLE_SPIX.
• 5. Add example Python smoke test at GrpcInterface/Python/rips/tests/test_spix_smoke.py. Protocol revision: Spix's AnyRPC server is XML-RPC, not JSON-RPC; test uses xmlrpc.client.ServerProxy. Final assertion: calls getErrors() (path-less) — verified end-to-end against a running ResInsight.exe --spix-port 9000. An earlier draft asserted existsAndVisible("mainWindow") but that returned False because no top-level widget calls setObjectName(...); resolving that is a precondition for path-based UI tests, not for the smoke check.

Approach

1. vcpkg manifest

File: vcpkg.json

Add "spix" to the dependencies array. vcpkg pulls in anyrpc automatically (both ports already live in microsoft/vcpkg).

The vcpkg spix port builds Spix::QtQuick by default. We need Spix::QtWidgets, which the port exposes via the qtwidgets feature; switch the dependencies entry to the object form:

{ "name": "spix", "features": ["qtwidgets"] }

(Verify the feature name when implementing — vcpkg's ports/spix/vcpkg.json is the source of truth. If the port lacks a qtwidgets feature, fall back to adding SPIX_BUILD_QTWIDGETS=ON via a custom triplet in ThirdParty/vcpkg-custom-triplets/.)

2. CMake option and link wiring

File: CMakeLists.txt

After the existing RESINSIGHT_ENABLE_GRPC block (around line 245), add:

option(RESINSIGHT_ENABLE_SPIX
       "Enable Spix UI test automation (HTTP/RPC server)" OFF)
if(RESINSIGHT_ENABLE_SPIX)
  find_package(Spix CONFIG REQUIRED)
  add_definitions(-DENABLE_SPIX)
endif()

File: ApplicationExeCode/CMakeLists.txt

Inside the existing if(RESINSIGHT_ENABLE_GRPC) neighborhood (~line 183 or where LINK_LIBRARIES is assembled, line 206), add:

if(RESINSIGHT_ENABLE_SPIX)
  list(APPEND LINK_LIBRARIES Spix::QtWidgets)
endif()

3. CLI flag

File: ApplicationLibCode/Application/Tools/RiaArgumentParser.cpp:75

Register a new option next to portnumberfile:

progOpt->registerOption(\"spix-port\",
                        \"<portnumber>\",
                        \"Start Spix UI test automation server on the given HTTP port.\",
                        cvf::ProgramOptions::SINGLE_VALUE);

No #ifdef here — unknown options are harmless; the server only starts when the option is handled in the GUI app, which is gated on ENABLE_SPIX.

4. Server lifetime in the GUI app

Files:

• ApplicationLibCode/Application/RiaGuiApplication.h
• ApplicationLibCode/Application/RiaGuiApplication.cpp

In the header, behind #ifdef ENABLE_SPIX:

• Forward-declare namespace spix { class AnyRpcServer; class QtWidgetsTestServer; }
• Add two std::unique_ptr members.

In RiaGuiApplication::handleArguments (RiaGuiApplication.cpp near line 531) — not in initialize(), because the port is parsed from the CLI — add:

#ifdef ENABLE_SPIX
if (cvf::Option o = progOpt->option(\"spix-port\")) {
    int port = (o.valueCount() == 1) ? o.value(0).toInt() : 0;
    if (port > 0) startSpixServer(port);
}
#endif

Implement startSpixServer(int) as a private method that constructs spix::AnyRpcServer and a Spix QtWidgetsTestServer, stores them in the members, and calls their start method. Stop them in ~RiaGuiApplication (~line 210) before the windows are torn down.

The exact Spix QtWidgets API surface (class names: QtWidgetsBot vs QtWidgetsTestServer) shifted between releases — read spix/QtWidgetsBot.h from the vcpkg-installed include tree at implementation time and use whatever the headers expose.

5. Example Python test

New file: GrpcInterface/Python/rips/tests/test_spix_smoke.py

Minimal smoke test that:

1. Skips with pytest.skip(...) if RESINSIGHT_SPIX_PORT env var is unset (keeps it out of the default CI suite, since CI doesn't launch ResInsight with --spix-port).
2. POSTs a getProperty mainWindow visible JSON-RPC request to http://localhost:<port> using urllib.request (no new deps).
3. Asserts the response is valid JSON with result == true.

Use the stdlib-only style of existing tests (see test_launch.py for the pattern).

Files modified

File	Change
vcpkg.json	Add spix (with qtwidgets feature)
CMakeLists.txt	Add RESINSIGHT_ENABLE_SPIX option, find_package(Spix)
ApplicationExeCode/CMakeLists.txt	Conditionally link Spix::QtWidgets
ApplicationLibCode/Application/Tools/RiaArgumentParser.cpp	Register --spix-port
ApplicationLibCode/Application/RiaGuiApplication.h	Forward-decl + members
ApplicationLibCode/Application/RiaGuiApplication.cpp	Start/stop server
GrpcInterface/Python/rips/tests/test_spix_smoke.py	New example test

Verification

1. Default build (Spix off): cmake --build --preset x64-relwithdebinfo — must succeed, ResInsight binary unchanged in size/behavior. No spix in the linker line.

2. Spix-enabled build:
   ```
   cmake . --preset x64-relwithdebinfo -DRESINSIGHT_ENABLE_SPIX=ON
   cmake --build --preset x64-relwithdebinfo --target ResInsight
   ```
   Confirm vcpkg installed spix and anyrpc, ResInsight links them.

3. Runtime smoke:
   ```
   build\RelWithDebInfo\ResInsight.exe --spix-port 9000
   ```
   In another shell:
   ```
   curl -s -X POST http://localhost:9000 -H "Content-Type: application/json"
   -d '{"jsonrpc":"2.0","id":1,"method":"command","params":["getProperty","mainWindow","visible"]}'
   ```
   Expect a JSON response with result: true.

4. Python test:
   ```
   $env:RESINSIGHT_SPIX_PORT=9000
   python -m pytest GrpcInterface\Python\rips\tests\test_spix_smoke.py -v
   ```
   With ResInsight running with --spix-port 9000, test passes. Without the env var, test is skipped.

5. No-flag run: launch ResInsight without --spix-port. Confirm no listening socket appears — server only starts when the flag is given.

Risks / open items

• Spix's exact Qt 6.4+ compatibility on Windows + MSVC 2022 should be confirmed during step 2. If the vcpkg port fails to build with the project's compiler flags (e.g., /W4 or WARNINGS_AS_ERRORS), wrap the Spix target in set_target_properties(... INTERFACE_SYSTEM_INCLUDE_DIRECTORIES ...) the way Arrow::arrow_shared is treated in CMakeLists.txt:725.
• The qtwidgets feature flag for the vcpkg spix port has to be verified against vcpkg/ports/spix/vcpkg.json — if it doesn't exist, custom triplet fallback is the next step.
• Spix headers expose Q_OBJECT types; if AUTOMOC has trouble with them in a unity build, exclude the relevant translation unit from unity (mirroring the UNITY_EXCLUDE_FILES pattern in ApplicationExeCode/CMakeLists.txt:242).

[magnesj]

Runtime data flow

sequenceDiagram
    participant Test as External script<br/>(Python / curl)
    participant Server as spix::AnyRpcServer<br/>(in ResInsight process)
    participant Bot as spix::QtWidgetsTestServer
    participant UI as Qt widget tree

    Note over Server: Started only when<br/>--spix-port <n> is passed
    Test->>Server: HTTP POST JSON-RPC<br/>command(getProperty, mainWindow, visible)
    Server->>Bot: Dispatch command
    Bot->>UI: Resolve widget by object name path<br/>+ read property
    UI-->>Bot: Property value
    Bot-->>Server: Result
    Server-->>Test: JSON-RPC response { result: true }

Loading

The HTTP/AnyRPC server runs inside RiaGuiApplication and shares its event loop with the Qt UI, so commands dispatched by Spix execute on the GUI thread. The --spix-port flag is the only entry point — without it the server is never constructed, and with RESINSIGHT_ENABLE_SPIX=OFF the entire start path is #ifdef'd out.

[magnesj]

Session summary — 2026-04-30

No implementation work was performed in this session. The branch feature/spix-integration-925 was created from dev (at 605662062c) but contains no commits beyond dev.

What happened:

• Reviewed the plan and enumerated the 5 numbered approach sections as discrete steps.
• Restructured the issue body to include a ## Steps checklist for tracking progress (none checked yet), and added a Mermaid sequence diagram in a separate comment to make the runtime flow explicit.

Open questions to resolve before implementation begins:

• vcpkg spix port feature name. Plan assumes the qtwidgets feature exists. Needs verification against microsoft/vcpkg/ports/spix/vcpkg.json (or by attempting the build and reading the error). Fallback is a custom triplet under ThirdParty/vcpkg-custom-triplets/ that sets SPIX_BUILD_QTWIDGETS=ON.
• Spix QtWidgets API surface. Class names (AnyRpcServer, QtWidgetsTestServer vs QtWidgetsBot) shifted between Spix releases. The exact symbols to use must be read from the vcpkg-installed spix/QtWidgetsBot.h after step 1 lands and the package is materialized — the plan's code snippets for step 4 are illustrative, not authoritative.
• MSVC + /W4 + WARNINGS_AS_ERRORS interaction. Spix headers may produce warnings under the project's strict flags; risk Update CommandFile.md with exportSimWellFractureCompletion doc #1 in the plan covers the workaround (INTERFACE_SYSTEM_INCLUDE_DIRECTORIES, mirror of Arrow::arrow_shared at CMakeLists.txt:725).

Next session should start at step 1 (vcpkg manifest) and verify the feature name as the first concrete check.

[m13v]

i went down the spix path on a Qt 6 app last year for QA hooks. HTTP server inside the process worked great until we tried two test sessions in parallel. AnyRpc serialized requests at the socket layer, so our 200-test suite went from 8 minutes to 40. switched to driving via platform accessibility (AXUIElement on mac, UIA on windows) and got real concurrency back, at the cost of mapping widget paths to accessibility roles by hand. for in-process single-threaded tests spix is still the right tool. one gotcha worth flagging in the gating step: pin the vcpkg spix version, because the qt 6.5 inputMethodHints change broke our text-entry steps and we had to bisect to find it.

[magnesj]

Commits

Branch: feature/spix-integration-925 (off dev at 605662062c). Not pushed.

SHA	Description	Date
bf30bb214c	Add vcpkg dependency with qtwidgets feature	2026-04-30
241ffac0d8	Add RESINSIGHT_ENABLE_SPIX CMake option	2026-04-30
321fb7d8d4	Register --spix-port command line option	2026-04-30
e1540a682b	Start AnyRPC server on --spix-port in RiaGuiApplication	2026-04-30
ba1911010f	Add Python smoke test using xmlrpc.client	2026-04-30
292dc6761c	Apply clang-format to header	2026-04-30
b845b975e6	Pin spix port to newer vcpkg baseline (superseded by FetchContent pivot)	2026-04-30
0cbf7a98cc	Build via FetchContent instead of vcpkg	2026-04-30
d657fe4eac	Link Spix::QtWidgets directly into ApplicationLibCode	2026-04-30
a676136	Smoke test calls getErrors() instead of existsAndVisible	2026-04-30

Two early commits (bf30bb214c, b845b975e6) are functionally undone by the FetchContent pivot in 0cbf7a98cc. They are kept in the branch history for traceability of the design pivot; an interactive rebase to drop them is an option before opening a PR.

[magnesj]

Implementation session — 2026-04-30

All five plan steps are committed locally on feature/spix-integration-925. Both build configurations were exercised end-to-end:

• Default build (Spix off): cmake --build build --target ResInsight succeeds; ResInsight.exe is unchanged in behaviour.
• Spix-enabled build (RESINSIGHT_ENABLE_SPIX=ON): SpixCore.lib and SpixQtWidgets.lib are produced under build/_deps/spix-build/, anyrpc.dll is staged next to ResInsight.exe, and ResInsight.exe links Spix transitively through ApplicationLibCode.

Key deviations from the original plan

1. vcpkg → FetchContent for Spix. The vcpkg spix port pulls in qtbase and qtdeclarative as transitive deps, which would force a duplicate Qt6 build. Pivoted to FetchContent_Declare(spix GIT_TAG v0.14) + add_subdirectory, with SPIX_BUILD_QTQUICK=OFF. This lets Spix find the project's existing system Qt6 via the inherited CMAKE_PREFIX_PATH. Only anyrpc remains a vcpkg dep.

2. Linkage site moved from ApplicationExeCode to ApplicationLibCode. RiaGuiApplication.cpp lives in ApplicationLibCode, so it needs Spix headers at compile time. Linking Spix::QtWidgets PUBLIC into ApplicationLibCode propagates both headers and link to ResInsight.exe automatically. An attempt to route the link via the project-wide THIRD_PARTY_LIBRARIES variable failed because Spix::QtWidgets is an ALIAS target, incompatible with the set_property(TARGET ${THIRD_PARTY_LIBRARIES} PROPERTY FOLDER "Thirdparty") walk near the end of the top-level CMakeLists.txt.

3. Smoke test protocol XML-RPC, not JSON-RPC. Reading libs/Core/src/AnyRpcServer.cpp upstream confirmed the server is anyrpc::XmlHttpServer. The plan's getProperty mainWindow visible JSON-RPC payload is not a registered method either — the actual API exposes existsAndVisible(path) -> bool. Test now uses xmlrpc.client.ServerProxy (stdlib, no new deps) and calls existsAndVisible("mainWindow").

4. CMakeUserPresets.json enables Spix on the local machine. Added "RESINSIGHT_ENABLE_SPIX": true to the windows-base preset. This file is gitignored (user-local), so the change does not enter version control — the project default remains OFF.

Concurrency note

A user comment on this issue flagged that AnyRPC serializes requests at the socket layer, so parallel test sessions against a single ResInsight instance will queue. For our intended single-session smoke-test workflow this is fine, but worth knowing if the test suite ever scales to parallel sessions.

Open verification items

• The smoke test was not run end-to-end against a live ResInsight.exe --spix-port 9000 in this session; only the build artifacts were verified. Next step is a manual launch + pytest round-trip.
• clang-format ran clean on the modified C++ files. ruff format and ruff check pass on the new Python test.
• No CI changes were made. CI does not pass -DRESINSIGHT_ENABLE_SPIX=ON, so the Spix code path is not exercised on CI.

[magnesj]

i went down the spix path on a Qt 6 app last year for QA hooks. HTTP server inside the process worked great until we tried two test sessions in parallel. AnyRpc serialized requests at the socket layer, so our 200-test suite went from 8 minutes to 40. switched to driving via platform accessibility (AXUIElement on mac, UIA on windows) and got real concurrency back, at the cost of mapping widget paths to accessibility roles by hand. for in-process single-threaded tests spix is still the right tool. one gotcha worth flagging in the gating step: pin the vcpkg spix version, because the qt 6.5 inputMethodHints change broke our text-entry steps and we had to bisect to find it.

@m13v Thanks for your comment. Appreciate that you share your experiences.

[magnesj]

Smoke test execution — 2026-04-30 (follow-up)

Smoke test now verified end-to-end against a live build:

• Launched build\ResInsight.exe --spix-port 9000. Confirmed listener on 0.0.0.0:9000 via netstat.
• Ran pytest --noconftest GrpcInterface/Python/rips/tests/test_spix_smoke.py → 1 passed in 2.10s.
• Verified skip path: same command without RESINSIGHT_SPIX_PORT set → 1 skipped.
• Issued xmlrpc.client.ServerProxy(...).quit() → ResInsight exited cleanly, no orphan process.

Findings during execution

existsAndVisible("mainWindow") returned False. Spix resolves widget paths by walking QApplication::topLevelWidgets() and matching objectName() (see libs/Scenes/QtWidgets/src/FindQtWidget.cpp:178). RiuMainWindow::RiuMainWindow() does not call setObjectName(...), so no top-level widget answers to "mainWindow". The smoke test was switched to getErrors() (no widget path required) so the integration check stays decoupled from widget naming.

conftest.py interference. The repo's GrpcInterface/Python/rips/tests/conftest.py calls rips.Instance.launch(...) at session start, which requires RESINSIGHT_EXECUTABLE to be set and would launch a second ResInsight via gRPC — a conflict for our use case. Worked around with pytest --noconftest. If the Spix smoke test is ever moved into a CI suite, it should live outside the rips fixture root or get a dedicated session that doesn't load that conftest.

Follow-up items (not done in this session)

• Name top-level widgets for path-based UI tests. RiuMainWindow (and likely RiuPlotMainWindow) need setObjectName("mainWindow") / setObjectName("plotMainWindow") if Spix is going to drive menus/buttons by path. This is a Spix-usability change, not a wiring change — out of scope for the integration plan but a natural next step for anyone authoring real UI tests.
• Live smoke test in CI. Wiring would need a CI job that builds with RESINSIGHT_ENABLE_SPIX=ON, launches the binary headlessly with --spix-port, runs the test, then sends quit. Currently no such job exists; the test stays skipped on default CI.