tests: misc: dtdoctor: add real-toolchain integration test

Exercise the DT Doctor SCA scripts end to end using the ctest harness:
the application builds normally, then ctest runs deliberately-failing
compile and link commands with the build's own toolchain through the
real SCA wrapper against the build's edt.pickle, and checks the
resulting diagnosis. The hermetic pytest suite from
scripts/tests/dtdoctor runs as a separate ctest entry, so the scripts
are fully covered by twister with no dedicated CI workflow.

The scenario builds with both SDK toolchains (integration_toolchains:
zephyr/gnu and zephyr/llvm) so the gcc/GNU ld and the clang/lld error
formats are both exercised. Also covered: the disabled-node diagnosis
(source location, chosen/alias references) and the enabled-node
headline against the real generated Kconfig environment.

Assisted-by: Claude:claude-fable-5
Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>

Author: kartben

tests/misc/dtdoctor/CMakeLists.txt

@@ -0,0 +1,34 @@
+# SPDX-FileCopyrightText: Copyright The Zephyr Project Contributors
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.28.0)
+
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+
+project(dtdoctor_test)
+target_sources(app PRIVATE src/main.c)
+
+enable_testing()
+include(CTest)
+
+# Hermetic unit tests for the dtdoctor scripts (fixture DTS and Kconfig trees)
+add_test(
+  NAME dtdoctor_unit
+  COMMAND ${PYTHON_EXECUTABLE} -m pytest ${ZEPHYR_BASE}/scripts/tests/dtdoctor -v
+)
+
+add_test(
+  NAME dtdoctor_e2e
+  COMMAND ${PYTHON_EXECUTABLE} -m pytest
+    ${CMAKE_CURRENT_SOURCE_DIR}/verify_dtdoctor.py
+    --build-dir ${CMAKE_BINARY_DIR}
+    --cc ${CMAKE_C_COMPILER}
+    -v
+)
+
+# Reproduce the Kconfig environment the dtdoctor SCA launcher runs with, so the
+# analyzer can parse the full Zephyr Kconfig tree for the enabled-node diagnosis
+set_tests_properties(
+  dtdoctor_e2e
+  PROPERTIES ENVIRONMENT "${COMMON_KCONFIG_ENV_SETTINGS}"
+)

tests/misc/dtdoctor/app.overlay

@@ -0,0 +1,30 @@
+/*
+ * SPDX-FileCopyrightText: Copyright The Zephyr Project Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/*
+ * dtdoctor_disabled is the target of the deliberately-failing builds in
+ * verify_dtdoctor.py; the chosen entry and alias below must show up in its
+ * diagnosis. dtdoctor_enabled exercises the "enabled but no driver" path
+ * (vnd,dtdoctor-device deliberately has no driver).
+ */
+/ {
+	chosen {
+		dtdoctor,dev = &dtdoctor_disabled;
+	};
+
+	aliases {
+		dtdoctor-dev = &dtdoctor_disabled;
+	};
+
+	dtdoctor_disabled: dtdoctor-disabled-device {
+		compatible = "vnd,dtdoctor-device";
+		status = "disabled";
+	};
+
+	dtdoctor_enabled: dtdoctor-enabled-device {
+		compatible = "vnd,dtdoctor-device";
+		status = "okay";
+	};
+};

tests/misc/dtdoctor/conftest.py

@@ -0,0 +1,51 @@
+# SPDX-FileCopyrightText: Copyright The Zephyr Project Contributors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Pytest configuration for the DT Doctor integration test."""
+
+import pickle
+import sys
+from pathlib import Path
+
+import pytest
+
+ZEPHYR_BASE = Path(__file__).parents[3]
+sys.path.insert(0, str(ZEPHYR_BASE / "scripts" / "dts" / "python-devicetree" / "src"))
+
+
+def pytest_addoption(parser):
+    parser.addoption(
+        "--build-dir",
+        action="store",
+        required=True,
+        help="Path to the build directory of the test application",
+    )
+    parser.addoption(
+        "--cc",
+        action="store",
+        required=True,
+        help="Path to the C compiler the application was built with",
+    )
+
+
+@pytest.fixture(scope="session")
+def build_dir(request):
+    return Path(request.config.getoption("--build-dir"))
+
+
+@pytest.fixture(scope="session")
+def cc(request):
+    return request.config.getoption("--cc")
+
+
+@pytest.fixture(scope="session")
+def edt_pickle(build_dir):
+    return build_dir / "zephyr" / "edt.pickle"
+
+
+@pytest.fixture(scope="session")
+def edt(edt_pickle):
+    from devicetree import edtlib  # noqa: F401 (needed to unpickle the EDT)
+
+    with open(edt_pickle, "rb") as f:
+        return pickle.load(f)

tests/misc/dtdoctor/dts/bindings/vnd,dtdoctor-device.yaml

@@ -0,0 +1,6 @@
+# SPDX-FileCopyrightText: Copyright The Zephyr Project Contributors
+# SPDX-License-Identifier: Apache-2.0
+
+description: Fake device without a driver, used by the DT Doctor integration test
+
+compatible: "vnd,dtdoctor-device"

tests/misc/dtdoctor/prj.conf

@@ -0,0 +1 @@
+# nothing here

tests/misc/dtdoctor/src/main.c

@@ -0,0 +1,9 @@
+/*
+ * SPDX-FileCopyrightText: Copyright The Zephyr Project Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+int main(void)
+{
+	return 0;
+}

tests/misc/dtdoctor/tests.yaml

@@ -0,0 +1,15 @@
+common:
+  tags:
+    - devicetree
+    - sca
+  harness: ctest
+  timeout: 120
+tests:
+  sca.dtdoctor:
+    integration_platforms:
+      - qemu_cortex_m3
+    platform_allow:
+      - qemu_cortex_m3
+    integration_toolchains:
+      - zephyr/gnu
+      - zephyr/llvm

tests/misc/dtdoctor/verify_dtdoctor.py

@@ -0,0 +1,94 @@
+# SPDX-FileCopyrightText: Copyright The Zephyr Project Contributors
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+End-to-end DT Doctor checks, run by ctest against a real application build.
+
+The analyzer and the SCA wrapper are exercised as real subprocesses against the
+build's edt.pickle, with deliberately-failing compile and link commands using
+the same toolchain the application was built with.
+"""
+
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+ZEPHYR_BASE = Path(__file__).parents[3]
+ANALYZER = ZEPHYR_BASE / "scripts" / "dts" / "dtdoctor_analyzer.py"
+WRAPPER = ZEPHYR_BASE / "scripts" / "dts" / "dtdoctor_sca_wrapper.py"
+
+
+def ord_symbol(edt, label):
+    return f"__device_dts_ord_{edt.label2node[label].dep_ordinal}"
+
+
+def run_analyzer(edt_pickle, symbol):
+    return subprocess.run(
+        [sys.executable, str(ANALYZER), "--edt-pickle", str(edt_pickle), "--symbol", symbol],
+        capture_output=True,
+        text=True,
+    )
+
+
+def run_wrapper_around(cmd, edt_pickle):
+    return subprocess.run(
+        [sys.executable, str(WRAPPER), "--edt-pickle", str(edt_pickle), "--", *cmd],
+        capture_output=True,
+        text=True,
+    )
+
+
+def test_analyzer_reports_disabled_node(edt, edt_pickle):
+    proc = run_analyzer(edt_pickle, ord_symbol(edt, "dtdoctor_disabled"))
+    assert proc.returncode == 0
+    assert "DT Doctor" in proc.stdout
+    assert "is disabled in" in proc.stdout
+    assert "dtdoctor-disabled-device" in proc.stdout
+    assert "'dtdoctor,dev'" in proc.stdout
+    assert "'dtdoctor-dev'" in proc.stdout
+    assert "'status' property to 'okay'" in proc.stdout
+
+
+def test_analyzer_reports_enabled_node_without_driver(edt, edt_pickle):
+    proc = run_analyzer(edt_pickle, ord_symbol(edt, "dtdoctor_enabled"))
+    assert proc.returncode == 0
+    assert "is enabled but no driver" in proc.stdout
+
+
+TESTDATA_SNIPPETS = [
+    "int dev = __device_dts_ord_{ordinal};\n",
+    "int get_dev(void) {{ return __device_dts_ord_{ordinal}; }}\n",
+]
+
+
+@pytest.mark.parametrize('template', TESTDATA_SNIPPETS, ids=['file-scope', 'function-scope'])
+def test_wrapper_diagnoses_compile_error(edt, edt_pickle, cc, tmp_path, template):
+    ordinal = edt.label2node["dtdoctor_disabled"].dep_ordinal
+    bad_c = tmp_path / "bad.c"
+    bad_c.write_text(template.format(ordinal=ordinal), encoding="utf-8")
+    proc = run_wrapper_around([cc, "-c", str(bad_c), "-o", str(tmp_path / "bad.o")], edt_pickle)
+    assert proc.returncode != 0
+    assert "DT Doctor" in proc.stdout
+    assert "is disabled in" in proc.stdout
+
+
+def test_wrapper_diagnoses_link_error(edt, edt_pickle, cc, tmp_path):
+    ordinal = edt.label2node["dtdoctor_disabled"].dep_ordinal
+    bad_c = tmp_path / "bad.c"
+    bad_c.write_text(
+        f"extern int __device_dts_ord_{ordinal};\n"
+        f"int main(void) {{ return __device_dts_ord_{ordinal}; }}\n",
+        encoding="utf-8",
+    )
+    obj = tmp_path / "bad.o"
+    subprocess.run([cc, "-c", str(bad_c), "-o", str(obj)], check=True)
+
+    link_cmd = [cc, str(obj), "-nostdlib", "-o", str(tmp_path / "bad.elf")]
+    proc = run_wrapper_around(link_cmd, edt_pickle)
+    assert proc.returncode != 0
+    if "undefined reference" not in proc.stderr and "undefined symbol" not in proc.stderr:
+        pytest.skip(f"unsupported linker error format: {proc.stderr[:200]}")
+    assert "DT Doctor" in proc.stdout
+    assert "is disabled in" in proc.stdout