feat(soc_filtered_targets): add support for selecting specific target sets

Author: horw

docs/usages/markers.rst

@@ -157,16 +157,43 @@ SOC Related Targets
 
 If you need to retrieve targets filtered by a specific SOC attribute, you can use the ``soc_filtered_targets`` function.
 
-This function processes both ``supported`` and ``preview`` targets, applies the specified filter, and returns a list of targets that match the given SOC attribute.
+This function processes both ``supported_targets`` and ``preview_targets``, applies the specified filter, and returns a list of targets that match the given SOC statement.
+
+**Function Signature**
+
+.. code:: python
+
+   def soc_filtered_targets(soc_statement: str, targets: ValidTargets = 'all') -> list[str]:
+       """Filters targets based on a given SOC (System on Chip) statement."""
+
+**Valid Target Categories**
+
+The ``targets`` parameter determines which target sets should be considered:
+
+-  ``"supported_targets"``: Includes only officially supported targets.
+-  ``"preview_targets"``: Includes only preview (experimental) targets.
+-  ``"all"`` (default): Includes both supported and preview targets.
 
 **Example:**
 
+Filter all targets that support ULP:
+
 .. code:: python
 
    from pytest_embedded_idf.utils import soc_filtered_targets
 
    @idf_parametrize('target', soc_filtered_targets('SOC_ULP_SUPPORTED != 1'), indirect=['target'])
-   def test_ulp_supported_targets(case_tester) -> None:
+   def test_all_targets_which_support_ulp(case_tester) -> None:
+       pass
+
+Filter only **supported** targets that support ULP:
+
+.. code:: python
+
+   from pytest_embedded_idf.utils import soc_filtered_targets
+
+   @idf_parametrize('target', soc_filtered_targets('SOC_ULP_SUPPORTED != 1', targets="supported_targets"), indirect=['target'])
+   def test_only_supported_targets_which_support_ulp(case_tester) -> None:
        pass
 
 Markers

pytest-embedded-idf/pytest_embedded_idf/utils.py

@@ -93,10 +93,31 @@ def decorator(func):
     return decorator
 
 
-def soc_filtered_targets(soc_statement: str) -> t.List[str]:
+ValidTargets = t.Literal['supported_targets', 'preview_targets', 'all']
+
+
+def soc_filtered_targets(soc_statement: str, targets: ValidTargets = 'all') -> t.List[str]:
+    """Filters targets based on a given SOC (System on Chip) statement.
+
+    Args:
+        soc_statement (str): A boolean expression used to filter targets.
+        targets (ValidTargets, optional): Specifies which target set to filter.
+            - "supported_targets": Filters only supported targets.
+            - "preview_targets": Filters only preview targets.
+            - "all": Filters both supported and preview targets.
+            Defaults to "all".
+
+    Returns:
+        List[str]: A list of targets that satisfy the given SOC statement.
+    """
+    target_list = []
+    target_list.extend(supported_targets.get()) if targets in ['all', 'supported_targets'] else []
+    target_list.extend(preview_targets.get()) if targets in ['all', 'preview_targets'] else []
+
     stm = parse_bool_expr(soc_statement)
+
     result = []
-    for target in [*supported_targets.get(), *preview_targets.get()]:
+    for target in target_list:
         if stm.get_value(target, ''):
             result.append(target)
     return result

pytest-embedded-idf/tests/test_idf.py

@@ -1167,6 +1167,9 @@ def test_soc_filtered_targets(testdir, copy_mock_esp_idf, monkeypatch):  # noqa:
         'esp32h2',
         'esp32c5',
     ]
+    assert soc_filtered_targets('SOC_A == 1', 'all') == ['esp32c3', 'esp32s3', 'esp32c6', 'esp32c5']
+    assert soc_filtered_targets('SOC_A == 1', targets='supported_targets') == ['esp32c3', 'esp32s3', 'esp32c6']
+    assert soc_filtered_targets('SOC_A == 1', targets='preview_targets') == ['esp32c5']
 
 
 def test_skip_if_soc_target_in_args(testdir, copy_mock_esp_idf, monkeypatch):  # noqa: ARG001