# Opp Repl Module Image Tests

> Detect visual regressions in OMNeT++ module rendering. capture_module_images renders one image per compound module from each filtered simulation (via Qtenv); run_module_image_tests compares fresh renders against a baseline using an RMSE metric. Distinct from chart tests (which compare analysis plots). Requires the httpx extra. Load when module display strings, icons, or layout must stay stable.

- Skill: `tabgab/opp-repl-module-image-tests` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tabgab/opp-repl-module-image-tests`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tabgab/opp-repl-module-image-tests/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tabgab (https://skillmd.com/u/tabgab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tabgab/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.