feat: link JUnit XML properties to sphinx-needs fields by cpolzer · Pull Request #135 · useblocks/sphinx-test-reports

cpolzer · 2026-05-12T19:22:47Z

Summary

This PR adds support for JUnit XML <properties> elements, enabling requirement traceability by mapping test case and test suite properties to sphinx-needs fields.

The entire properties feature is opt-in. If you don't set tr_extra_options or tr_property_link_types, the extension behaves exactly as it did before this PR.

Use Case

Many test frameworks (e.g., pytest with custom markers, Maven Surefire, JUnit 5) can embed key-value properties in JUnit XML output. These properties often contain requirement IDs, priorities, or categories. Previously, sphinx-test-reports ignored this data. Now you can surface it directly in your documentation and link tests back to requirements.

Example JUnit XML

<testcase classname="auth.tests" name="test_login" time="0.42">
  <properties>
    <property name="verifies" value="REQ_AUTH_001,REQ_AUTH_002"/>
    <property name="priority" value="high"/>
  </properties>
</testcase>

New Configuration Options

Option	Type	Description
`tr_extra_options`	`list[str]`	Which JUnit property names become sphinx-needs fields
`tr_property_link_types`	`dict[str, str]`	Maps a property name to a sphinx-needs link field (e.g. `"links"`)

Example `conf.py`

# Make these JUnit properties available as need fields
tr_extra_options = ["verifies", "priority", "category"]

# Map the "verifies" property to sphinx-needs links
tr_property_link_types = {
    "verifies": "links",  # comma-separated IDs → need links
}

What Changed

Parser (junitparser.py): Extracts <properties> from both <testcase> and <testsuite> elements with a safe guard against empty <properties/>.
Test Case Directive (directives/test_case.py): Flattens allowed properties into top-level fields; processes tr_property_link_types to build semicolon-separated sphinx-needs link values.
Test Suite Directive (directives/test_suite.py): Same property flattening and link mapping at the suite level.
Field Registration (test_reports.py): Automatically registers tr_extra_options as sphinx-needs fields on startup. Duplicate registration is handled gracefully (logs debug, no error).
Config (config.py): Added "properties" to the default JUnit parser options list.
Tests (test_properties.py): 384 lines of tests covering parser extraction, empty properties, integration build, DOM rendering, link creation, and backward compatibility.

Backward Compatibility

Fully backward compatible. If tr_extra_options and tr_property_link_types are not set, behavior is identical to before.
Property flattening is filtered through the tr_extra_options allowlist, so unknown properties never leak into add_need().

Test Coverage

Parser unit tests for property extraction
Empty <properties/> handling
Integration build with real JUnit XML
HTML DOM assertions for rendered fields
Link creation and merging
Backward compatibility (no config → no change)

Replace deprecated add_extra_option() with add_field() for sphinx-needs >= 8.0.0, using a version-gated shim that falls back to add_extra_option() for older versions. Also adds sphinx-needs 8.0.0 to the CI and nox test matrices, fixes the warning check in tests to also inspect stderr (where Sphinx writes warnings), adds a test asserting the test-file need node renders correctly, and removes the broken taplo pre-commit hook (taplo 0.9.3 PyPI package fails to build on this platform).

…inks Add support for JUnit XML <properties> elements at both testsuite and testcase level, enabling requirement traceability by mapping property values to sphinx-needs fields and links. - Parse <properties>/<property> from testcase and testsuite elements - Add tr_extra_options config to declare which properties become fields - Add tr_property_link_types config to map properties to sphinx-needs links - Register extra options as sphinx-needs fields with duplicate-safe handling - Guard against empty <properties/> elements without children - Filter property flattening through tr_extra_options allowlist - Add tests for parser extraction, empty properties, integration build, DOM field rendering, link creation, and backward compatibility

patdhlk

Thanks for the PR. In addition to the duplication of the file we need some documentation. I see no changes to docs/ or README. The user-facing PR description is good, but those config options should be in the rendered docs.

patdhlk · 2026-05-15T11:09:54Z

+        allowed_extras = set(getattr(self.app.config, "tr_extra_options", []))
+        case_properties = case.get("properties", {})
+        for prop_name, prop_value in case_properties.items():
+            if prop_name in allowed_extras and prop_name not in case:
+                case[prop_name] = prop_value
+
+        # Process tr_property_link_types: map property values to sphinx-needs links
+        tr_property_link_types = getattr(self.app.config, "tr_property_link_types", {})
+        for prop_name, link_field in tr_property_link_types.items():
+            prop_value = case_properties.get(prop_name, "")
+            if prop_value:
+                # Convert comma-separated IDs to semicolon-separated (sphinx-needs link format)
+                link_ids = ";".join(
+                    id_val.strip() for id_val in prop_value.split(",") if id_val.strip()
+                )
+                if link_field == "links":
+                    existing = self.test_links
+                else:
+                    existing = self.extra_options.get(link_field, "")
+                if existing:
+                    merged = existing + ";" + link_ids
+                else:
+                    merged = link_ids
+                if link_field == "links":
+                    self.test_links = merged
+                else:
+                    self.extra_options[link_field] = merged


@cpolzer same code/logic as in test_suite.py L76-L110

@patdhlk moved to "test_common .py" to deduplicate.

Extract the duplicated tr_property_link_types loop from test_case.py and test_suite.py into _apply_property_links() on TestCommonDirective. Add tr_property_link_types section to docs/configuration.rst and expand the tr_extra_options section to cover JUnit <properties> mapping.

cpolzer · 2026-05-20T08:21:43Z

Thanks for the PR. In addition to the duplication of the file we need some documentation. I see no changes to docs/ or README. The user-facing PR description is good, but those config options should be in the rendered docs.

@patdhlk added user facing docs - sphinx , skipped readme it has no configuration content as of now.

patdhlk

LGTM 🚀

StephenWithPH · 2026-05-29T01:13:55Z

This is exactly what I need. Thank you for the PR.

I think there is a slight error:

sphinx-test-reports/docs/configuration.rst

Lines 167 to 169 in 7031972

    
           tr_property_link_types 
        
           ---------------------- 
        
           .. versionadded:: 1.3.0

The current deployed docs show this as available since 1.3.0; 1.3.2 (current on PyPI) was released 11/13/25.

@patdhlk ... possible to cut a release to get this shipped?

## Release v1.4.0 Bumps the version (`pyproject.toml`, `docs/conf.py`, `test_reports.py`) and adds the 1.4.0 changelog for everything merged since 1.3.2. **Highlights** - Feature (#135): map JUnit XML `<properties>` to Sphinx-Needs fields/links. - Sphinx-Needs 8 support (#133): fields registered via the new `add_field` API. - Bugfix (#133): `file`, `suite`, `case`, `case_name`, `case_parameter` and `classname` are now registered with a typed schema → default to `None` → stripped before schema validation, fixing false-positive `Unevaluated properties are not allowed` warnings under `unevaluatedProperties: false`. Released 1.3.2 registered them untyped (default `""`), which leaked. - Bugfix (#134): JUnit `<error>` test cases were misclassified as `passed`; now handled correctly in `parse_testcase()`. - Testing (#130, #137): run against Sphinx-Needs 6.3.0; regression test that a strict schema ignores unpopulated Sphinx-Test-Reports fields. - Docs (#136, #139): clarify Sphinx-Needs type names vs. the hyphenated directives; note that numeric `cases` filtering requires Sphinx-Needs >= 6.

~chrstian polzer and others added 3 commits May 12, 2026 19:12

🔧 Restore taplo pre-commit hook

97cae91

cpolzer changed the title ~~feat: link JUnit XML properties to sphinx-needs fields and requirement links~~ feat: link JUnit XML properties to sphinx-needs fields May 12, 2026

patdhlk requested changes May 15, 2026

View reviewed changes

patdhlk self-requested a review May 20, 2026 09:02

patdhlk approved these changes May 20, 2026

View reviewed changes

patdhlk merged commit 7031972 into useblocks:master May 20, 2026
25 checks passed

arnoox mentioned this pull request May 21, 2026

Showcase: Use sphinx-test-reports JUnit XML properties for requirement traceability useblocks/sphinx-needs-demo#62

Open

4 tasks

Copilot AI mentioned this pull request May 21, 2026

Showcase JUnit XML <properties> for requirement traceability via sphinx-test-reports useblocks/sphinx-needs-demo#63

Draft

ubmarco mentioned this pull request Jun 16, 2026

🚀 Release v1.4.0 #138

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: link JUnit XML properties to sphinx-needs fields#135

feat: link JUnit XML properties to sphinx-needs fields#135
patdhlk merged 4 commits into
useblocks:masterfrom
cpolzer:feature/linking-by-property

cpolzer commented May 12, 2026

Uh oh!

patdhlk left a comment

Uh oh!

patdhlk May 15, 2026 •

edited

Loading

Uh oh!

cpolzer May 20, 2026

Uh oh!

cpolzer commented May 20, 2026

Uh oh!

patdhlk left a comment

Uh oh!

Uh oh!

StephenWithPH commented May 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

cpolzer commented May 12, 2026

Summary

Use Case

Example JUnit XML

New Configuration Options

Example conf.py

What Changed

Backward Compatibility

Test Coverage

Uh oh!

patdhlk left a comment

Choose a reason for hiding this comment

Uh oh!

patdhlk May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cpolzer May 20, 2026

Choose a reason for hiding this comment

Uh oh!

cpolzer commented May 20, 2026

Uh oh!

patdhlk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

StephenWithPH commented May 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Example `conf.py`

patdhlk May 15, 2026 •

edited

Loading