tests/unittests: allow out-of-tree tests

This adds and documents the new `EXTERNAL_UNIT_TEST_DIRS` environment
variable that allows including out-of-tree unit tests. The intention is
to allow users of `EXTERNAL_MODULE_DIRS` to also provide corresponding
unit tests and run them all with a single test app.

Co-authored-by: crasbe <[email protected]>

Author: maribu

doc/guides/advanced_tutorials/creating_application.md

@@ -343,3 +343,11 @@ APPLICATION = my_app
 PROJECT_BASE ?= $(CURDIR)/../..
 include $(PROJECT_BASE)/Makefile.include
 ```
+
+### Unit Tests for External Modules
+
+When writing external modules, it can be helpful to make use of the existing
+unit test infrastructure in `tests/unittests` to run both upstream unit tests
+as well as downstream project-specific unit tests in a single app. For this the
+environment variable `EXTERNAL_UNITTEST_DIRS` can be used to list directories
+(separated by a space) to additional unit tests.

makefiles/app_dirs.blacklist

@@ -11,6 +11,8 @@ tests/build_system/external_board_native/external_boards/
 tests/build_system/external_module_dirs/external_modules/
 tests/build_system/external_pkg_dirs/external_pkgs/
 tests/build_system/kconfig/external_modules/
+tests/build_system/external_unittests/external_tests_dir/
+tests/build_system/external_unittests/tests-in_tree
 tests/build_system/kconfig/external_pkgs/
 tests/periph/qdec/boards_modded/
 tests/pkg/openwsn_sock_udp/external_modules/

tests/build_system/external_unittests/Makefile

@@ -0,0 +1,11 @@
+# Run this only on native64 / native, as this rather tests the build system
+# than the code actually run.
+
+BOARD_WHITELIST := native native64
+
+EXTERNAL_UNITTEST_DIRS := $(CURDIR)/external_tests_dir
+
+# Build upon tests/unittests:
+RIOTBASE ?= $(CURDIR)/../../..
+UNIT_TESTS_DIR := $(CURDIR)/../../unittests
+include ../../unittests/Makefile

tests/build_system/external_unittests/README.md

@@ -0,0 +1,16 @@
+External Unit Tests
+===================
+
+This test apps provides two trivial unit tests: One provided internally in the
+folder of this unit tests apps and one provided externally via a variable.
+Since the test only validates correct operation of the build system, there is
+little value in running it on more than one board. For this reason, the app is
+limited to be build only for native / native64.
+
+Implementation Details
+----------------------
+
+The two tests contain a reference to a variable of the other tests, so that
+the app will not link if only if both of the unit tests are available at
+link time (or none). In addition, the python test runner will check that two
+ tests are executed (to rule out that none was available).

tests/build_system/external_unittests/external_tests_dir/tests-out_of_tree/Makefile

@@ -0,0 +1 @@
+include $(RIOTBASE)/Makefile.base

tests/build_system/external_unittests/external_tests_dir/tests-out_of_tree/tests-out-of-tree.c

@@ -0,0 +1,35 @@
+/*
+ * Copyright (C) 2025 ML!PA Consulting GmbH
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser
+ * General Public License v2.1. See the file LICENSE in the top level
+ * directory for more details.
+ */
+
+#include <stdio.h>
+
+#include "embUnit.h"
+
+const unsigned external_test_was_linked_in = 1;
+
+static void test_internal_test_was_linked_in(void)
+{
+    extern const unsigned internal_test_was_linked_in;
+    TEST_ASSERT_EQUAL_INT(1, internal_test_was_linked_in);
+}
+
+static Test *out_of_tree_tests(void)
+{
+    EMB_UNIT_TESTFIXTURES(fixtures) {
+        new_TestFixture(test_internal_test_was_linked_in),
+    };
+
+    EMB_UNIT_TESTCALLER(_out_of_tree_tests, NULL, NULL, fixtures);
+
+    return (Test *)&_out_of_tree_tests;
+}
+
+void tests_out_of_tree(void)
+{
+    TESTS_RUN(out_of_tree_tests());
+}

tests/build_system/external_unittests/main.c

@@ -0,0 +1 @@
+../../unittests/main.c

tests/build_system/external_unittests/map.h

@@ -0,0 +1 @@
+../../unittests/map.h

tests/build_system/external_unittests/tests-in_tree/Makefile

@@ -0,0 +1 @@
+include $(RIOTBASE)/Makefile.base

tests/build_system/external_unittests/tests-in_tree/tests-in-tree.c

@@ -0,0 +1,35 @@
+/*
+ * Copyright (C) 2025 ML!PA Consulting GmbH
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser
+ * General Public License v2.1. See the file LICENSE in the top level
+ * directory for more details.
+ */
+
+#include <stdio.h>
+
+#include "embUnit.h"
+
+const unsigned internal_test_was_linked_in = 1;
+
+static void test_external_test_was_linked_in(void)
+{
+    extern const unsigned external_test_was_linked_in;
+    TEST_ASSERT_EQUAL_INT(1, external_test_was_linked_in);
+}
+
+static Test *in_tree_tests(void)
+{
+    EMB_UNIT_TESTFIXTURES(fixtures) {
+        new_TestFixture(test_external_test_was_linked_in),
+    };
+
+    EMB_UNIT_TESTCALLER(_in_tree_tests, NULL, NULL, fixtures);
+
+    return (Test *)&_in_tree_tests;
+}
+
+void tests_in_tree(void)
+{
+    TESTS_RUN(in_tree_tests());
+}