From 0c96117a6a976833be8ca0e676de9276695e54af Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 7 May 2026 09:52:01 +0000
Subject: [PATCH] Add test for need role in section heading and fix NeedRef
 node registration

The NeedRef node was not registered with app.add_node(), causing
SphinxContentsFilter to fail when encountering it in section headings
(used for TOC generation). Fixed by registering NeedRef with dummy
visitor methods.

Agent-Logs-Url: https://github.com/useblocks/sphinx-needs/sessions/383d8ee1-76c6-41b3-b820-931501775be8

Co-authored-by: chrisjsewell <2997570+chrisjsewell@users.noreply.github.com>
---
 sphinx_needs/needs.py                         |  5 ++++
 .../doc_test/doc_role_need_in_heading/conf.py | 11 +++++++++
 .../doc_role_need_in_heading/index.rst        | 10 ++++++++
 tests/test_role_need_in_heading.py            | 24 +++++++++++++++++++
 4 files changed, 50 insertions(+)
 create mode 100644 tests/doc_test/doc_role_need_in_heading/conf.py
 create mode 100644 tests/doc_test/doc_role_need_in_heading/index.rst
 create mode 100644 tests/test_role_need_in_heading.py

diff --git a/sphinx_needs/needs.py b/sphinx_needs/needs.py
index c8aba344d..345028d29 100644
--- a/sphinx_needs/needs.py
+++ b/sphinx_needs/needs.py
@@ -245,6 +245,11 @@ def setup(app: Sphinx) -> dict[str, Any]:
         html=(visitor_dummy, visitor_dummy),
         latex=(visitor_dummy, visitor_dummy),
     )
+    app.add_node(
+        NeedRef,
+        html=(visitor_dummy, visitor_dummy),
+        latex=(visitor_dummy, visitor_dummy),
+    )
 
     ########################################################################
     # DIRECTIVES
diff --git a/tests/doc_test/doc_role_need_in_heading/conf.py b/tests/doc_test/doc_role_need_in_heading/conf.py
new file mode 100644
index 000000000..0e006d7e1
--- /dev/null
+++ b/tests/doc_test/doc_role_need_in_heading/conf.py
@@ -0,0 +1,11 @@
+extensions = ["sphinx_needs"]
+
+needs_types = [
+    {
+        "directive": "req",
+        "title": "Requirement",
+        "prefix": "RE_",
+        "color": "#BFD8D2",
+        "style": "node",
+    },
+]
diff --git a/tests/doc_test/doc_role_need_in_heading/index.rst b/tests/doc_test/doc_role_need_in_heading/index.rst
new file mode 100644
index 000000000..eea06be95
--- /dev/null
+++ b/tests/doc_test/doc_role_need_in_heading/index.rst
@@ -0,0 +1,10 @@
+Test Need Role in Heading
+=========================
+
+.. req:: My Requirement
+   :id: REQ_001
+
+Section with need ref :need:`REQ_001`
+-------------------------------------
+
+Some content here.
diff --git a/tests/test_role_need_in_heading.py b/tests/test_role_need_in_heading.py
new file mode 100644
index 000000000..896d34800
--- /dev/null
+++ b/tests/test_role_need_in_heading.py
@@ -0,0 +1,24 @@
+import re
+from pathlib import Path
+
+import pytest
+
+
+@pytest.mark.parametrize(
+    "test_app",
+    [{"buildername": "html", "srcdir": "doc_test/doc_role_need_in_heading"}],
+    indirect=True,
+)
+def test_role_need_in_heading(test_app):
+    app = test_app
+    app.build()
+    html = Path(app.outdir, "index.html").read_text()
+
+    # The heading should contain a reference to the need
+    heading = re.search(r"<h2>(.*?)</h2>", html, re.DOTALL)
+    assert heading is not None, "Expected an h2 heading in the output"
+    heading_content = heading.group(1)
+
+    # The heading should contain a link to the need with the resolved title
+    assert "REQ_001" in heading_content
+    assert "My Requirement" in heading_content