Opp repl module image tests

Module-image tests

Module-image tests render the network/module visualization that Qtenv would draw (display strings, icons, layout, submodule arrangement) and compare it against a stored baseline image. This catches regressions in NED display strings and visualization code — something neither fingerprint tests (event behavior) nor chart tests (analysis plots) cover.

Upstream reference: https://github.com/omnetpp/opp_repl/blob/main/doc/module_image_tests.md

Requirements

pip install "opp_repl[mcp]"   # provides httpx, used to drive Qtenv

Baseline images live in the project's module_image_baseline_folder.

Python API

# 1. Seed/refresh the baseline (first run, or after intended changes)
update_module_image_test_results(simulation_project=inet_project)

# 2. Run the comparison
r = run_module_image_tests(simulation_project=inet_project)

# 3. Capture images to an arbitrary directory (e.g. for review)
capture_module_images(simulation_project=inet_project,
                      output_dir="/tmp/inet-modules")

run_module_image_tests returns MultipleTestTaskResults with PASS / FAIL / SKIP / ERROR per simulation (see opp-repl-tasks-and-results).

Command line

opp_capture_module_images            --load inet.opp -p inet --output-dir /tmp/imgs
opp_update_module_image_test_results --load inet.opp -p inet
opp_run_module_image_tests           --load inet.opp -p inet

--output-dir is required for opp_capture_module_images.

Useful options (CLI and kwargs)

Option	Meaning
--module-path-filter	glob on a module's full path (e.g. **.host[*])
--module-type-filter	glob on a module's NED type
--group-by	path (default) / type / path_no_indices
--area	all_elements (default) / module_rectangle / viewport
--margin	pixels around the captured area (default 5)
--startup-timeout	seconds to wait per simulation's MCP endpoint (default 30)
--metric-threshold	max RMSE for a PASS (default 0 = pixel-perfect)
--baseline-simulation-project	project supplying the baseline (run only)

Loosen --metric-threshold slightly (e.g. 2.0) when minor anti-aliasing noise causes spurious FAILs.

Pitfalls

• Rendering drives Qtenv through opp_repl's MCP machinery, so the mcp extra (httpx) must be installed even for a "headless" run.
• Fonts, Qt version, and display scaling change the pixels. Pin the toolchain (ideally a fixed container) across baseline and CI, like chart tests.
• Pixel-perfect default (--metric-threshold 0) is strict; a one-pixel shift FAILs. Use a small RMSE threshold for stability.
• This is a different suite from chart tests — keep their baselines and thresholds separate.

See also

• opp-repl-chart-tests — visual regression for analysis plots.
• opp-repl-tasks-and-results — inspect FAIL/ERROR results.
• opp-repl-running-simulations — underlying run machinery.
• opp-repl-feature-and-release-tests — run as part of a full suite.