From 6d9097b4ea958c2b80c1fac71bf2cf3eee2c734d Mon Sep 17 00:00:00 2001 From: Levente Meszaros Date: Mon, 26 Oct 2026 17:03:06 +0100 Subject: [PATCH] doc: change: drop --load from the opp_repl commands in the INET tree The documentation wrote each fingerprint command as `opp_run_fingerprint_tests --load $INET_ROOT -p inet ...`. In the INET tree, the two options are not necessary, and they make each example longer. opp_repl c24d2c6 makes a command look for *.opp files in the current folder and then in its parent folders, as git finds its repository. So in each folder of the INET tree a command finds INET's inet.opp, and it finds the project from the current folder. The developer guide explains this once, with the --load $INET_ROOT -p inet form for a folder outside the INET tree, and the other pages use the short form. The comment of inet.opp says the same. The script fingerprinttest_selfdoc and the workflows keep the long form, so that they do not depend on the current folder. Checked in the GitHub-job container with opp_repl c24d2c6: the short form gives the 3 PASS of examples/empty from the INET root with -f, from examples/empty without an option and from tests/fingerprint with -f. In /tmp, the command finds no project without an option, and gives the 3 PASS with --load $INET_ROOT -p inet. Plan: plan/pending/tests-on-opp-repl.md Change: doc | behavior.change | - | tests-on-opp-repl --- doc/project/guide/change-a-baseline.md | 4 +-- doc/project/guide/run-the-gates.md | 2 +- doc/src/developers-guide/ch-testing.rst | 28 +++++++++++-------- .../development/tests-fingerprint-store.rst | 7 +++-- inet.opp | 4 +-- tests/fingerprint/README | 6 ++-- tutorials/fingerprint/doc/accepting.rst | 4 +-- tutorials/fingerprint/doc/first.rst | 4 +-- tutorials/fingerprint/doc/refactoring.rst | 2 +- .../doc/renaming_module_parameter.rst | 6 ++-- 10 files changed, 36 insertions(+), 31 deletions(-) diff --git a/doc/project/guide/change-a-baseline.md b/doc/project/guide/change-a-baseline.md index 9be0bdfcb70..c7467e99b8c 100644 --- a/doc/project/guide/change-a-baseline.md +++ b/doc/project/guide/change-a-baseline.md @@ -19,14 +19,14 @@ If investigation is still needed, keep the failing outputs as evidence. Investig ## 3. Check the scope of the movement ```bash -opp_run_fingerprint_tests --load $INET_ROOT -p inet -f '' +opp_run_fingerprint_tests -f '' ``` Start with an explicit filter for the configurations directly related to the changed contract and record the command, mode, configuration, run/seed, status and generated artifacts ([TR-FOCUSED-EVIDENCE](../rule/testing.md#tr-focused-evidence)). A broader integration run may then look for collateral movement, but it does not replace the focused evidence. A change that moves far more configurations than expected is telling you something. A serializer change that moves a mobility fingerprint is not a serializer change. ## 4. Regenerate -After approval, regenerate only the baselines the change actually moves. A blanket regeneration sweeps up unrelated drift and hides it under your reason. For fingerprints, run `opp_update_fingerprint_test_results --load $INET_ROOT -p inet -f ''` with the filter of step 3, and read `git diff tests/fingerprint/store.json`. +After approval, regenerate only the baselines the change actually moves. A blanket regeneration sweeps up unrelated drift and hides it under your reason. For fingerprints, run `opp_update_fingerprint_test_results -f ''` with the filter of step 3, and read `git diff tests/fingerprint/store.json`. ## 5. Commit it with the change that causes it diff --git a/doc/project/guide/run-the-gates.md b/doc/project/guide/run-the-gates.md index bd844fed6c4..856669d5206 100644 --- a/doc/project/guide/run-the-gates.md +++ b/doc/project/guide/run-the-gates.md @@ -22,7 +22,7 @@ Map each changed path, symbol or behavioral contract to the directly related cas ```bash doc/project/enforcement/check-architecture.sh src/inet/ -opp_run_fingerprint_tests --load $INET_ROOT -p inet -f '' +opp_run_fingerprint_tests -f '' # Use the category runner's explicit selector for unit, module, protocol and other tests. ``` diff --git a/doc/src/developers-guide/ch-testing.rst b/doc/src/developers-guide/ch-testing.rst index 096a7ce5bf5..ca2946657cd 100644 --- a/doc/src/developers-guide/ch-testing.rst +++ b/doc/src/developers-guide/ch-testing.rst @@ -32,15 +32,19 @@ for each concrete config that can run without user input, and some more runs. The fingerprint tests run with the :command:`opp_run_fingerprint_tests` command of `opp_repl `__. Set up the OMNeT++ and INET -environment first. Then run all fingerprint tests from anywhere in the INET tree: +environment first. Then run all fingerprint tests from the INET root: .. code-block:: shell - $ opp_run_fingerprint_tests --load $INET_ROOT -p inet + $ cd $INET_ROOT + $ opp_run_fingerprint_tests -The ``--load $INET_ROOT`` option loads INET's project description, the file -:file:`inet.opp` in the INET root, and ``-p inet`` selects INET. From the INET root, -opp_repl loads the file without the option. The description sets the store, the +The opp_repl commands find INET's project description, the file :file:`inet.opp` in +the INET root, without an option: they look for ``*.opp`` files in the current folder +and then in its parent folders. So the commands of this chapter work in each folder +of the INET tree. In a subfolder, a command without a filter tests only that +subfolder. Outside the INET tree, add ``--load $INET_ROOT -p inet``. The description +sets the store, the ingredients that CI checks (``tplx``, ``~tNl`` and ``~tND``) and a CPU time limit of 600s for each simulation. The command shows its options with ``-h``. @@ -60,7 +64,7 @@ For example, the following command runs all wireless tests in release mode: .. code-block:: shell - $ opp_run_fingerprint_tests --load $INET_ROOT -p inet -m release -f wireless + $ opp_run_fingerprint_tests -m release -f wireless While the tests are running, the command prints a line for each simulation. The test result of each fingerprint is PASS, FAIL or ERROR, and a FAIL line shows the @@ -78,13 +82,13 @@ To accept new fingerprints, run the update command with the same filter: .. code-block:: shell - $ opp_update_fingerprint_test_results --load $INET_ROOT -p inet -f wireless + $ opp_update_fingerprint_test_results -f wireless The update runs each stored run at its stored limit, and writes the new values into the store. It reports KEEP, UPDATE or INSERT for each simulation, and :command:`git diff tests/fingerprint/store.json` shows the changed values. A new config gets its run-0 fingerprints with ``--no-stored-only``, for example -``opp_update_fingerprint_test_results --load $INET_ROOT -p inet --no-stored-only -c '^MyConfig$' -r 0``. +``opp_update_fingerprint_test_results --no-stored-only -c '^MyConfig$' -r 0``. The new entries take the ``sim-time-limit`` of the ini file. Usually, when a simulation model is being developed, the fingerprint tests should @@ -126,8 +130,8 @@ the affected runs. After the change, check them: .. code-block:: shell - $ opp_update_fingerprint_test_results --load $INET_ROOT -p inet --no-stored-only -f -r 0 --ingredients plx - $ opp_run_fingerprint_tests --load $INET_ROOT -p inet -f --ingredients plx + $ opp_update_fingerprint_test_results --no-stored-only -f -r 0 --ingredients plx + $ opp_run_fingerprint_tests -f --ingredients plx Another common example is when a submodule is renamed. Since the default fingerprint ingredients contain the full module path of all events, this change will break @@ -147,8 +151,8 @@ and the test after the change. ``--append-args`` passes the rest of the line to .. code-block:: shell # please note the quoting uses both ' and " in the right order - $ opp_update_fingerprint_test_results --load $INET_ROOT -p inet -f --append-args --fingerprint-modules='"not(fullPath(**.wlan[*].mac.**))"' - $ opp_run_fingerprint_tests --load $INET_ROOT -p inet -f --append-args --fingerprint-modules='"not(fullPath(**.wlan[*].mac.**))"' + $ opp_update_fingerprint_test_results -f --append-args --fingerprint-modules='"not(fullPath(**.wlan[*].mac.**))"' + $ opp_run_fingerprint_tests -f --append-args --fingerprint-modules='"not(fullPath(**.wlan[*].mac.**))"' INET uses continuous integration on Github. Fingerprint and other tests are run automatically for changes on the master and integration branches. Moreover, all diff --git a/doc/src/migration-guide/development/tests-fingerprint-store.rst b/doc/src/migration-guide/development/tests-fingerprint-store.rst index 8debf4873c4..c170f70adc4 100644 --- a/doc/src/migration-guide/development/tests-fingerprint-store.rst +++ b/doc/src/migration-guide/development/tests-fingerprint-store.rst @@ -5,12 +5,13 @@ INET no longer has its own fingerprint test tool. The baseline is the JSON store ``tests/fingerprint/store.json``, and the commands of opp_repl run and update it. Install opp_repl as the GitHub workflow does, with ``pip install "opp_repl @ git+https://github.com/omnetpp/opp_repl.git@github_ci"``, set up the OMNeT++ -and INET environment, and run the commands from anywhere in the INET tree: +and INET environment, and run the commands in the INET tree, where they find INET's +:file:`inet.opp` by themselves: .. code-block:: bash - opp_run_fingerprint_tests --load $INET_ROOT -p inet -m release -f wireless - opp_update_fingerprint_test_results --load $INET_ROOT -p inet -m release -f wireless + opp_run_fingerprint_tests -m release -f wireless + opp_update_fingerprint_test_results -m release -f wireless The second command replaces the ``.UPDATED`` files of ``fingerprinttest``: it writes the new values into the store, and ``git diff`` shows them. The command diff --git a/inet.opp b/inet.opp index 789177e4b00..c4282148c11 100644 --- a/inet.opp +++ b/inet.opp @@ -16,8 +16,8 @@ SimulationProject( msg_folders=["src"], # INET's description for opp_repl. It lives in the INET repository, so that a change of INET's # test setup lands with the INET change; opp_repl bundles an older copy as a fallback for INET - # versions without this file. Load it with --load $INET_ROOT (or from the INET root, where - # opp_repl loads every *.opp file of the current folder). + # versions without this file. An opp_repl command finds this file without an option in the + # INET root and in each folder below it; elsewhere, load it with --load $INET_ROOT. # # Per-kind test configuration. Only INET-specific aspects are declared here; # opp_repl's generic defaults (run everything, mode=debug, smoke/sanitizer diff --git a/tests/fingerprint/README b/tests/fingerprint/README index 8d73d482e20..79f18f0e1bd 100644 --- a/tests/fingerprint/README +++ b/tests/fingerprint/README @@ -22,10 +22,10 @@ The ethernet-*.ini files of this folder are simulations that exist only for the fingerprint test. Run the tests and accept new values with the opp_repl commands, after -the OMNeT++ and INET setenv: +the OMNeT++ and INET setenv, anywhere in the INET tree: - opp_run_fingerprint_tests --load $INET_ROOT -p inet [-f ] - opp_update_fingerprint_test_results --load $INET_ROOT -p inet [-f ] + opp_run_fingerprint_tests [-f ] + opp_update_fingerprint_test_results [-f ] doc/src/developers-guide/ch-testing.rst describes the options. diff --git a/tutorials/fingerprint/doc/accepting.rst b/tutorials/fingerprint/doc/accepting.rst index 8680ed9cd6a..33996911a0e 100644 --- a/tutorials/fingerprint/doc/accepting.rst +++ b/tutorials/fingerprint/doc/accepting.rst @@ -13,7 +13,7 @@ First, run the fingerprint tests with the ``tplx`` ingredients: .. code-block:: bash - $ opp_run_fingerprint_tests --load $INET_ROOT -p inet -w tutorials/fingerprint --ingredients tplx -c '^(Ethernet|Wifi)$' + $ opp_run_fingerprint_tests -w tutorials/fingerprint --ingredients tplx -c '^(Ethernet|Wifi)$' .. code-block:: fp @@ -25,7 +25,7 @@ The model is validated, so the new values are correct. Record them in the store: .. code-block:: bash - $ opp_update_fingerprint_test_results --load $INET_ROOT -p inet -w tutorials/fingerprint --ingredients tplx -c '^(Ethernet|Wifi)$' + $ opp_update_fingerprint_test_results -w tutorials/fingerprint --ingredients tplx -c '^(Ethernet|Wifi)$' .. code-block:: fp diff --git a/tutorials/fingerprint/doc/first.rst b/tutorials/fingerprint/doc/first.rst index 3a15c448a09..7a45ccf1c0e 100644 --- a/tutorials/fingerprint/doc/first.rst +++ b/tutorials/fingerprint/doc/first.rst @@ -187,7 +187,7 @@ Always give the project and the working directory filter. Use ``tplx`` as the in .. code-block:: bash - $ opp_run_fingerprint_tests --load $INET_ROOT -p inet -w tutorials/fingerprint --ingredients tplx + $ opp_run_fingerprint_tests -w tutorials/fingerprint --ingredients tplx .. code-block:: fp @@ -205,7 +205,7 @@ For example, the `Changing a Timer` step needs the ``Wifi`` configuration only: .. code-block:: bash - $ opp_run_fingerprint_tests --load $INET_ROOT -p inet -w tutorials/fingerprint --ingredients tplx -c '^Wifi$' + $ opp_run_fingerprint_tests -w tutorials/fingerprint --ingredients tplx -c '^Wifi$' .. code-block:: fp diff --git a/tutorials/fingerprint/doc/refactoring.rst b/tutorials/fingerprint/doc/refactoring.rst index 83c70a5c052..ebd2d978a1e 100644 --- a/tutorials/fingerprint/doc/refactoring.rst +++ b/tutorials/fingerprint/doc/refactoring.rst @@ -18,6 +18,6 @@ The refactoring doesn't change the fingerprint because the code is functionally .. code-block:: fp - $ opp_run_fingerprint_tests --load $INET_ROOT -p inet -w tutorials/fingerprint --ingredients tplx -c '^(Ethernet|Wifi)$' + $ opp_run_fingerprint_tests -w tutorials/fingerprint --ingredients tplx -c '^(Ethernet|Wifi)$' tutorials/fingerprint -c Ethernet for 0.2s PASS tutorials/fingerprint -c Wifi for 5s PASS diff --git a/tutorials/fingerprint/doc/renaming_module_parameter.rst b/tutorials/fingerprint/doc/renaming_module_parameter.rst index 7a9e1d92e4b..a74102779e1 100644 --- a/tutorials/fingerprint/doc/renaming_module_parameter.rst +++ b/tutorials/fingerprint/doc/renaming_module_parameter.rst @@ -41,7 +41,7 @@ and the router doesn't forward packets. This change causes the fingerprint tests .. code-block:: bash - $ opp_run_fingerprint_tests --load $INET_ROOT -p inet -w tutorials/fingerprint --ingredients tplx -c '^Ethernet$' + $ opp_run_fingerprint_tests -w tutorials/fingerprint --ingredients tplx -c '^Ethernet$' .. code-block:: fp @@ -58,7 +58,7 @@ To correct the model, the renaming needs to be followed everywhere. When we chan .. code-block:: bash - $ opp_run_fingerprint_tests --load $INET_ROOT -p inet -w tutorials/fingerprint --ingredients tplx -c '^Ethernet$' + $ opp_run_fingerprint_tests -w tutorials/fingerprint --ingredients tplx -c '^Ethernet$' .. code-block:: fp @@ -77,7 +77,7 @@ When run the ``tplx`` fingerprint tests, they result in ERROR: .. code-block:: bash - $ opp_run_fingerprint_tests --load $INET_ROOT -p inet -w tutorials/fingerprint --ingredients tplx -c '^Ethernet$' + $ opp_run_fingerprint_tests -w tutorials/fingerprint --ingredients tplx -c '^Ethernet$' .. code-block:: fp