Skip to content

Commit 7cb45c3

Browse files
authored
added feature req option (#978)
Co-authored-by: FScholPer <FScholPer@users.noreply.github.com>
1 parent 1f9452a commit 7cb45c3

4 files changed

Lines changed: 152 additions & 6 deletions

File tree

‎docs/how-to/dashboards_and_quality_gates.rst‎

Lines changed: 32 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -60,9 +60,39 @@ explicit override in ``docs/conf.py``:
6060
When this setting is provided, the explicit list is used instead of
6161
autodiscovery.
6262

63-
Use ``score_metrics_include_external_needs = True`` only in repositories that
63+
Use ``score_metrics_include_external_needs = True`` in repositories that
6464
intentionally aggregate requirements across module dependencies, such as
65-
integration repositories.
65+
integration repositories, or combine it with the optional feature scope below.
66+
67+
Optional External Feature Scope
68+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
69+
70+
A module repository can report on feature requirements maintained in another
71+
repository, such as ``score``, without counting unrelated external requirements.
72+
First import that repository's needs data through the existing external-needs
73+
configuration, then configure the metrics in ``docs/conf.py``:
74+
75+
.. code-block:: python
76+
77+
score_metrics_include_external_needs = True
78+
score_metrics_requirement_types = "feat_req,comp_req,aou_req"
79+
score_metrics_external_feature_ids = ["feat__lifecycle"]
80+
81+
Replace the example feature ID with the exact ID referenced by the imported
82+
feature requirements' ``satisfied_by`` links. Multiple feature IDs are supported.
83+
All local requirements of the selected requirement types remain included.
84+
External requirements are included only if they are ``feat_req`` needs with a
85+
``satisfied_by`` link to at least one selected feature. Requirements without
86+
tests are still counted; unrelated external requirements are excluded.
87+
Local tests can link to the imported requirements through ``fully_verifies``
88+
or ``partially_verifies`` as usual. The metrics selection does not remove
89+
imported needs from the documentation or from test-reference resolution.
90+
91+
This feature is opt-in: ``score_metrics_external_feature_ids`` defaults to
92+
``[]``, preserving the existing local-only or full-aggregation behavior.
93+
The scope has no effect while ``score_metrics_include_external_needs`` is
94+
``False``. It does not import external needs automatically or change the
95+
configured requirement types.
6696

6797
Building the Dashboard
6898
----------------------

‎src/extensions/score_metrics/__init__.py‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,17 @@ def setup(app: Sphinx) -> dict[str, str | bool]:
7171
"Default is False so each repo gates only its own needs."
7272
),
7373
)
74+
app.add_config_value(
75+
"score_metrics_external_feature_ids",
76+
[],
77+
rebuild="env",
78+
types=[list],
79+
description=(
80+
"Optional feature IDs used to select external feat_req requirements "
81+
"by satisfied_by links when external needs are enabled. Local "
82+
"requirements remain included. Empty preserves full aggregation."
83+
),
84+
)
7485
app.setup_extension("score_metamodel")
7586

7687
# Calculates the metrics & sets global var for access

‎src/extensions/score_metrics/tests/test_traceability_metrics.py‎

Lines changed: 93 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,15 +11,18 @@
1111
# SPDX-License-Identifier: Apache-2.0
1212
# *******************************************************************************
1313

14+
from types import SimpleNamespace
1415
from typing import Any, cast
16+
from unittest.mock import MagicMock
1517

1618
import pytest
1719
import score_metrics.traceability_metrics as metrics
1820
from score_metamodel import ScoreNeedType
1921
from score_metamodel.tests import need as test_need
2022
from score_pytest.attribute_plugin import add_test_properties
21-
from sphinx_needs.data import NeedsView
22-
from sphinx_needs.need_item import NeedItem
23+
from sphinx.environment import BuildEnvironment
24+
from sphinx_needs.data import NeedsView, SphinxNeedsData
25+
from sphinx_needs.need_item import NeedItem, NeedItemSourceExternal
2326

2427

2528
@add_test_properties(
@@ -266,3 +269,91 @@ def test_calculate_test_metrics_counts_linked_tests_and_broken_refs() -> None:
266269
assert result["broken_references"] == [
267270
{"testcase": "TC_2", "missing_need": "REQ_404"}
268271
]
272+
273+
274+
@add_test_properties(
275+
partially_verifies=["tool_req__docs_test_linkage_metrics"],
276+
test_type="requirements-based",
277+
derivation_technique="equivalence-classes",
278+
)
279+
@pytest.mark.parametrize(
280+
("include_external", "feature_ids", "feature_total", "component_total"),
281+
[
282+
(False, None, 1, 1),
283+
(True, None, 6, 2),
284+
(True, [], 6, 2),
285+
(False, ["feat__lifecycle"], 1, 1),
286+
(True, ["feat__lifecycle"], 4, 1),
287+
(True, ["feat__lifecycle", "feat__other"], 5, 1),
288+
(True, ["feat__missing"], 1, 1),
289+
],
290+
)
291+
def test_calculate_full_need_metrics_optional_external_feature_scope(
292+
monkeypatch: pytest.MonkeyPatch,
293+
include_external: bool,
294+
feature_ids: list[str] | None,
295+
feature_total: int,
296+
component_total: int,
297+
) -> None:
298+
"""Scope external requirements by feature without hiding untested requirements."""
299+
external_requirements = [
300+
test_need(
301+
id="feat_req__linked",
302+
type="feat_req",
303+
satisfied_by=["feat__lifecycle"],
304+
testlink="TC_1",
305+
),
306+
test_need(
307+
id="feat_req__untested",
308+
type="feat_req",
309+
satisfied_by=["feat__lifecycle"],
310+
),
311+
test_need(
312+
id="feat_req__unrelated",
313+
type="feat_req",
314+
satisfied_by=["feat__other"],
315+
),
316+
test_need(
317+
id="feat_req__shared",
318+
type="feat_req",
319+
satisfied_by=["feat__lifecycle", "feat__other"],
320+
),
321+
test_need(id="feat_req__unassigned", type="feat_req"),
322+
test_need(id="comp_req__external", type="comp_req"),
323+
]
324+
for need in external_requirements:
325+
monkeypatch.setattr(
326+
need,
327+
"_source",
328+
NeedItemSourceExternal(url=f"https://example.org/{need.id}"),
329+
)
330+
needs = [
331+
*external_requirements,
332+
test_need(id="feat_req__local", type="feat_req"),
333+
test_need(id="comp_req__local", type="comp_req"),
334+
test_need(id="TC_1", type="testcase", fully_verifies=["feat_req__linked"]),
335+
]
336+
monkeypatch.setattr(metrics, "CALCULATED_METRICS", {})
337+
app = MagicMock()
338+
app.env = MagicMock(spec=BuildEnvironment)
339+
needs_data = SphinxNeedsData(app.env)
340+
for need in needs:
341+
needs_data.add_need(need)
342+
needs_data.needs_is_post_processed = True
343+
app.config = SimpleNamespace(
344+
score_metamodel_yaml=None,
345+
score_metrics_requirement_types="feat_req,comp_req",
346+
)
347+
if feature_ids is not None:
348+
app.config.score_metrics_external_feature_ids = feature_ids
349+
350+
metrics.calculate_full_need_metrics(app, include_external)
351+
352+
result = metrics.CALCULATED_METRICS
353+
assert result["metrics_by_type"]["feat_req"]["total"] == feature_total
354+
assert result["metrics_by_type"]["comp_req"]["total"] == component_total
355+
assert result["overall_metrics"]["total"] == feature_total + component_total
356+
expected_linked = int(include_external and feature_ids != ["feat__missing"])
357+
assert result["metrics_by_type"]["feat_req"]["with_test_link"] == expected_linked
358+
assert result["tests"]["linked_to_requirements"] == 1
359+
assert result["tests"]["broken_references"] == []

‎src/extensions/score_metrics/traceability_metrics.py‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -255,6 +255,9 @@ def calculate_full_need_metrics(app: Sphinx, include_external: bool):
255255
filter_reqs = [t.strip() for t in raw.split(",") if t.strip()]
256256
if not filter_reqs:
257257
filter_reqs = get_need_types_by_tags(metamodel.needs_types, {"requirement"})
258+
external_feature_ids = set(
259+
getattr(app.config, "score_metrics_external_feature_ids", [])
260+
)
258261
# ──────────────────[ Calculate Test Metrics ]──────────────────
259262

260263
test_needs = list(all_needs.filter_types(["testcase"]).values())
@@ -278,10 +281,21 @@ def calculate_full_need_metrics(app: Sphinx, include_external: bool):
278281
needs_of_req_type = all_needs.filter_types([req_type]).filter_is_external(
279282
False
280283
)
284+
selected_requirements = list(needs_of_req_type.values())
285+
if include_external and external_feature_ids:
286+
selected_requirements = [
287+
need
288+
for need in selected_requirements
289+
if not need.get("is_external")
290+
or (
291+
req_type == "feat_req"
292+
and external_feature_ids.intersection(need.get("satisfied_by", []))
293+
)
294+
]
281295
# We do not care if there is no requirements of this type.
282-
if not list(needs_of_req_type.values()):
296+
if not selected_requirements:
283297
continue
284-
req_metrics = calculate_requirement_metrics(list(needs_of_req_type.values()))
298+
req_metrics = calculate_requirement_metrics(selected_requirements)
285299
overall_metrics["total"] += req_metrics["total"]
286300
overall_metrics["with_code_link"] += req_metrics["with_code_link"]
287301
overall_metrics["with_test_link"] += req_metrics["with_test_link"]

0 commit comments

Comments
 (0)