From cd1696ed03b222da664385a58c4d10862a05d21a Mon Sep 17 00:00:00 2001 From: Parth Aggarwal Date: Fri, 27 Feb 2026 13:31:16 -0800 Subject: [PATCH] Add TIMED_TEST_SUITE_INITIALIZE/CLEANUP guidelines to coding instructions Document that test suites must use TIMED_TEST_SUITE_INITIALIZE and TIMED_TEST_SUITE_CLEANUP instead of the raw TEST_SUITE_INITIALIZE/CLEANUP macros. The timed versions inject a process watchdog that terminates test suites that hang, preventing CI pipelines from stalling. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/general_coding_instructions.md | 38 ++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/.github/general_coding_instructions.md b/.github/general_coding_instructions.md index 7a6f7798..da83d878 100644 --- a/.github/general_coding_instructions.md +++ b/.github/general_coding_instructions.md @@ -1127,6 +1127,44 @@ Test helper headers that are used across multiple tests should be included in th - This improves build times and reduces include duplication - PCH include must be the first include in the test file +### Test Suite Initialize and Cleanup + +Test suites must use `TIMED_TEST_SUITE_INITIALIZE` and `TIMED_TEST_SUITE_CLEANUP` from `c_pal/timed_test_suite.h` instead of `TEST_SUITE_INITIALIZE` / `TEST_SUITE_CLEANUP`. The timed versions inject a process watchdog that terminates the test process if a test suite hangs, preventing CI pipelines from stalling indefinitely. + +```c +#include "c_pal/timed_test_suite.h" + +// timeout_ms is required - use TIMED_TEST_DEFAULT_TIMEOUT_MS (10 minutes) or a custom value +TIMED_TEST_SUITE_INITIALIZE(TestSuiteInit, TIMED_TEST_DEFAULT_TIMEOUT_MS) +{ + // suite initialization code +} + +TIMED_TEST_SUITE_CLEANUP(TestSuiteCleanup) +{ + // suite cleanup code +} +``` + +Additional fixtures can be passed as variadic arguments, just like with the old macros: + +```c +TIMED_TEST_SUITE_INITIALIZE(TestSuiteInit, TIMED_TEST_DEFAULT_TIMEOUT_MS, my_extra_init_fixture) +{ + // suite initialization code +} + +TIMED_TEST_SUITE_CLEANUP(TestSuiteCleanup, my_extra_cleanup_fixture) +{ + // suite cleanup code +} +``` + +**Guidelines:** +- Do NOT use `TEST_SUITE_INITIALIZE` or `TEST_SUITE_CLEANUP` directly — they are internal macros and will produce a compile error +- Always include `c_pal/timed_test_suite.h` instead of `testrunnerswitcher.h` directly +- Use `TIMED_TEST_DEFAULT_TIMEOUT_MS` (10 minutes) unless a test suite needs a different timeout + ### Include Paths for Reals Headers When including real implementation headers in test files, use the header name directly without relative paths. The build system's `reals` target adds the correct include directory: