markers: new preferred_topology marker

Reducing test running time and system resources, we can now mark
a test with @pytest.mark.preferred_topology(KnownTopology.topology),
making the topology the single and default run unless the marker is
overridden. This is intended to be used for tests that do not need
to cover all topologies all the time.

Author: Dan Lavu

docs/articles/tips-and-tricks.rst

@@ -11,3 +11,4 @@ inspiration for your project.
     tips-and-tricks/building-command-line
     tips-and-tricks/features-detection
     tips-and-tricks/pytest-fixtures
+    tips-and-tricks/preferred-topology

docs/articles/tips-and-tricks/preferred-topology.rst

@@ -0,0 +1,34 @@
+Preferred Topology
+==================
+
+The preferred topology marker ``pytest.mark.preferred_topology`` can be
+used if you want the flexibility to run against all topologies, but do not
+need to do it all the time. An example could be Nightly builds or a CI where
+a single topology is adequate coverage. This will reduce the resources
+required to run the tests and their execution times. This is possible by using
+the ``pytest.mark.preferred_topology`` marker.
+
+This marks the test with a default topology, deselecting any additional
+topologies. ``--mh-ignore-preferred-topology`` can be used to ignore the
+marker.
+
+If more than one preferred topology has been defined, only the last topology
+will be used. If the preferred topology contains no value, the marker is
+ignored.The ``pytest.mark.preferred_topology`` marker accepts three types of
+values, :class:`~pytest_mh.TopologyMark` value of
+:class:`~pytest_mh.KnownTopologyBase` or ``str``.
+
+.. code-block:: python
+    :caption:  Example: set preferred topology to IPA
+
+
+    @pytest.mark.topology(KnownTopologyGroup.AnyProvider)
+    @pytest.mark.preferred_topology(KnownTopology.IPA)
+    def test_preferred_mark_known_topology_ipa():
+        pass
+
+
+    @pytest.mark.topology(KnownTopologyGroup.AnyProvider)
+    @pytest.mark.preferred_topology("ipa")
+    def test_preferred_mark_string_ipa():
+        pass

pytest_mh/_private/plugin.py

@@ -18,7 +18,7 @@
 from .errors import TeardownExceptionGroup
 from .fixtures import MultihostFixture
 from .logging import MultihostLogger
-from .marks import TopologyMark
+from .marks import KnownTopologyBase, TopologyMark
 from .multihost import (
     MultihostArtifactsMode,
     MultihostConfig,
@@ -63,6 +63,7 @@ def __init__(self, pytest_config: pytest.Config) -> None:
         self.mh_collect_artifacts: MultihostArtifactsMode = pytest_config.getoption("mh_collect_artifacts")
         self.mh_artifacts_dir: Path = Path(pytest_config.getoption("mh_artifacts_dir"))
         self.mh_compress_artifacts: bool = pytest_config.getoption("mh_compress_artifacts")
+        self.mh_ignore_preferred_topology: bool = pytest_config.getoption("mh_ignore_preferred_topology")
 
         # Read --mh-collect-logs, default to --mh-collect-artifacts
         self.mh_collect_logs: MultihostArtifactsMode = pytest_config.getoption("mh_collect_logs")
@@ -200,6 +201,7 @@ def pytest_sessionstart(self, session: pytest.Session) -> None:
         self.logger.info(f"  collect artifacts: {self.mh_collect_artifacts}")
         self.logger.info(f"  artifacts directory: {self.mh_artifacts_dir}")
         self.logger.info(f"  collect logs: {self.mh_collect_logs}")
+        self.logger.info(f"  ignore-preferred-topology: {self.mh_ignore_preferred_topology}")
         self.logger.info("")
 
         signal(SIGINT, self.sigint_handler)
@@ -521,6 +523,32 @@ def _create_logger(self, verbose) -> logging.Logger:
     def _is_multihost_required(self, item: pytest.Item) -> bool:
         return item.get_closest_marker(name="topology") is not None
 
+    def _can_run_preferred_topology(self, mark: pytest.Mark, current_topology: str, item: pytest.Item) -> bool:
+        if len(mark.args) != 1:
+            raise ValueError(
+                f"{item.nodeid}: Unexpected number of arguments to pytest.mark.preferred_topology: "
+                f"got {len(mark.args)}, expected 1"
+            )
+
+        arg = mark.args[0]
+
+        if isinstance(arg, KnownTopologyBase):
+            name = arg.value.name
+        elif isinstance(arg, TopologyMark):
+            name = arg.name
+        elif isinstance(arg, str):
+            name = arg
+        else:
+            raise ValueError(
+                f"{item.nodeid}: Unexpected type of pytest.mark.preferred_topology: "
+                f"got {type(arg)}, expected KnownTopologyBase | TopologyMark | str"
+            )
+
+        if name == current_topology:
+            return True
+
+        return False
+
     def _can_run_test(self, item: pytest.Item, data: MultihostItemData | None) -> bool:
         if data is None:
             return not self._is_multihost_required(item)
@@ -547,6 +575,12 @@ def _can_run_test(self, item: pytest.Item, data: MultihostItemData | None) -> bo
             if data.topology_mark.name not in self.mh_topology:
                 return False
 
+        # Run only for preferred topology unless specific topology is requested or the marker is ignored
+        if not self.mh_topology and not self.mh_ignore_preferred_topology:
+            preferred_topology = item.get_closest_marker(name="preferred_topology")
+            if preferred_topology is not None and data.topology_mark is not None:
+                return self._can_run_preferred_topology(preferred_topology, data.topology_mark.name, item)
+
         return True
 
     def _clone_function(self, name: str, f: pytest.Function) -> pytest.Function:
@@ -792,6 +826,12 @@ def pytest_addoption(parser):
 
     parser.addoption("--mh-lazy-ssh", action="store_true", help="Postpone connecting to host SSH until it is required")
 
+    parser.addoption(
+        "--mh-ignore-preferred-topology",
+        action="store_true",
+        help="All topologies will run, ignore the preferred_topology marker",
+    )
+
     parser.addoption(
         "--mh-topology",
         action="append",
@@ -862,6 +902,13 @@ def pytest_configure(config: pytest.Config):
         "the test is skipped if condition is not met",
     )
 
+    config.addinivalue_line(
+        "markers",
+        "preferred_topology(topology: KnownTopologyBase | TopologyMark | str): "
+        "mark test with a preferred topology."
+        "Test will execute once, skipping additional topologies",
+    )
+
     config.pluginmanager.register(MultihostPlugin(config), "MultihostPlugin")