fix(anta)!: Fix tags behavior to reflect the documentation (#903)

* fix(anta): Fix tags behavior

* Use total_test_count for better performance

* Update anta/runner.py

---------

Co-authored-by: Guillaume Mulocher <gmulocher@arista.com>

anta/runner.py

@@ -146,20 +146,26 @@ def prepare_tests(
     # Using a set to avoid inserting duplicate tests
     device_to_tests: defaultdict[AntaDevice, set[AntaTestDefinition]] = defaultdict(set)
 
+    total_test_count = 0
+
     # Create the device to tests mapping from the tags
     for device in inventory.devices:
         if tags:
-            if not any(tag in device.tags for tag in tags):
+            # If there are CLI tags, execute tests with matching tags for this device
+            if not (matching_tags := tags.intersection(device.tags)):
                 # The device does not have any selected tag, skipping
                 continue
+            device_to_tests[device].update(catalog.get_tests_by_tags(matching_tags))
         else:
             # If there is no CLI tags, execute all tests that do not have any tags
             device_to_tests[device].update(catalog.tag_to_tests[None])
 
-        # Add the tests with matching tags from device tags
-        device_to_tests[device].update(catalog.get_tests_by_tags(device.tags))
+            # Then add the tests with matching tags from device tags
+            device_to_tests[device].update(catalog.get_tests_by_tags(device.tags))
+
+        total_test_count += len(device_to_tests[device])
 
-    if len(device_to_tests.values()) == 0:
+    if total_test_count == 0:
         msg = (
             f"There are no tests{f' matching the tags {tags} ' if tags else ' '}to run in the current test catalog and device inventory, please verify your inputs."
         )

docs/cli/tag-management.md

@@ -4,9 +4,7 @@
   ~ that can be found in the LICENSE file.
   -->
 
-ANTA commands can be used with a `--tags` option. This option **filters the inventory** with the specified tag(s) when running the command.
-
-Tags can also be used to **restrict a specific test** to a set of devices when using `anta nrfu`.
+ANTA uses tags to define test-to-device mappings (tests run on devices with matching tags) and the `--tags` CLI option acts as a filter to execute specific test/device combinations.
 
 ## Defining tags
 

tests/data/test_inventory_with_tags.yml

@@ -3,7 +3,7 @@ anta_inventory:
   hosts:
     - name: leaf1
       host: leaf1.anta.arista.com
-      tags: ["leaf"]
+      tags: ["leaf", "dc1"]
     - name: leaf2
       host: leaf2.anta.arista.com
       tags: ["leaf"]

tests/units/test_runner.py

@@ -138,6 +138,7 @@ def side_effect_setrlimit(resource_id: int, limits: tuple[int, int]) -> None:
         pytest.param({"filename": "test_inventory_with_tags.yml"}, None, {"VerifyMlagStatus", "VerifyUptime"}, 3, 5, id="filtered-tests"),
         pytest.param({"filename": "test_inventory_with_tags.yml"}, {"leaf"}, {"VerifyMlagStatus", "VerifyUptime"}, 2, 4, id="1-tag-filtered-tests"),
         pytest.param({"filename": "test_inventory_with_tags.yml"}, {"invalid"}, None, 0, 0, id="invalid-tag"),
+        pytest.param({"filename": "test_inventory_with_tags.yml"}, {"dc1"}, None, 0, 0, id="device-tag-no-tests"),
     ],
     indirect=["inventory"],
 )