From 5f823ddd69f240794ff5721a7033707a29dbf05d Mon Sep 17 00:00:00 2001
From: Dave Lane <42013603+ReenigneArcher@users.noreply.github.com>
Date: Sat, 17 Oct 2026 12:53:21 -0400
Subject: [PATCH] test: standardize shared test header includes (#5951)

---
 AGENTS.md                                      | 14 ++++++++++++++
 tests/tests_common.h                           |  5 ++++-
 tests/unit/platform/linux/test_audio.cpp       |  4 +++-
 .../platform/linux/test_dynamic_loader.cpp     |  6 +++---
 tests/unit/platform/linux/test_kms_plane.cpp   |  6 +++---
 .../linux/test_kmsgrab_cursor_formats.cpp      |  6 +++++-
 tests/unit/platform/linux/test_misc.cpp        |  6 +++---
 tests/unit/platform/linux/test_wayland.cpp     |  6 +++---
 .../windows/test_nvprefs_undo_data.cpp         |  3 ---
 tests/unit/test_constructor_contracts.cpp      |  6 +++---
 tests/unit/test_crypto.cpp                     |  3 +--
 tests/unit/test_nvenc_dynamic_factory.cpp      |  6 +++---
 tests/unit/test_nvenc_utils.cpp                |  6 +++---
 tests/unit/test_nvenc_version.cpp              |  6 +++---
 tests/unit/test_nvhttp_client_auth.cpp         |  1 +
 tests/unit/test_rtsp.cpp                       |  6 +++---
 tests/unit/test_sync.cpp                       |  6 +++---
 tests/unit/test_system_tray.cpp                | 18 +++++++++---------
 tests/unit/test_task_pool.cpp                  |  4 ++--
 tests/unit/test_thread_safe.cpp                |  6 +++---
 20 files changed, 72 insertions(+), 52 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 6597c9f74..8b47e7b63 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -10,6 +10,16 @@ the build directory.
 
 The project uses gtest as a test framework.
 
+Sunshine tests must include `tests/tests_common.h` using the appropriate relative path, rather than including
+`<gtest/gtest.h>` directly. The common header provides GoogleTest through the shared test support and makes
+`TEST` use `BaseTest`, including its output capture and shared setup/teardown.
+
+Group test headers first under `// test includes`, followed by `// standard includes`, `// lib includes`, and
+`// local includes`, with a blank line between groups. Put shared test helpers in the test group, and omit empty
+groups. Keep platform-specific headers and their group comments inside the appropriate preprocessor guards.
+When a test depends on a particular include order, preserve that order and explain the dependency in a comment;
+do not move the common header ahead of headers whose first-include behavior is being tested.
+
 Add or update regression tests for new or modified source-code methods and behavior.
 Target 100% coverage on changed source code.
 
@@ -70,6 +80,10 @@ plan in the issue. This limit applies only to creating issues; investigate or fi
 
 ## Code Review Rules
 
+Check new and modified tests for the common-header and include-group conventions above. Request
+`tests_common.h` instead of direct GoogleTest includes, and ensure shared test helpers are in the test include
+group. Verify any documented include-order dependency before asking the author to reorder headers.
+
 Report concrete issues introduced by the change that the contributor can address. For each finding, explain the
 triggering condition, impact, and a practical fix; point to the relevant code or test. Keep workflow status separate
 from code findings.
diff --git a/tests/tests_common.h b/tests/tests_common.h
index 4544a381b..9f1d4a53e 100644
--- a/tests/tests_common.h
+++ b/tests/tests_common.h
@@ -1,6 +1,9 @@
 /**
  * @file tests/tests_common.h
- * @brief Common declarations.
+ * @brief Common GoogleTest support, BaseTest fixtures, and Sunshine test helpers.
+ *
+ * Include this header from Sunshine tests instead of including GoogleTest directly. The shared test support
+ * makes TEST use BaseTest so tests receive common setup, teardown, and output capture.
  */
 #pragma once
 
diff --git a/tests/unit/platform/linux/test_audio.cpp b/tests/unit/platform/linux/test_audio.cpp
index 5358f65df..19b962c55 100644
--- a/tests/unit/platform/linux/test_audio.cpp
+++ b/tests/unit/platform/linux/test_audio.cpp
@@ -5,12 +5,14 @@
 
 #ifdef __linux__
 
+  // test includes
+  #include "../../../tests_common.h"
+
   // standard includes
   #include <chrono>
   #include <vector>
 
   // lib includes
-  #include <gtest/gtest.h>
   #include <pulse/pulseaudio.h>
 
   // local includes
diff --git a/tests/unit/platform/linux/test_dynamic_loader.cpp b/tests/unit/platform/linux/test_dynamic_loader.cpp
index 9a9008db2..3593ea97e 100644
--- a/tests/unit/platform/linux/test_dynamic_loader.cpp
+++ b/tests/unit/platform/linux/test_dynamic_loader.cpp
@@ -4,15 +4,15 @@
  */
 #ifdef __linux__
 
+  // test includes
+  #include "../../../tests_common.h"
+
   // standard includes
   #include <bit>
 
   // platform includes
   #include <dlfcn.h>
 
-  // lib includes
-  #include <gtest/gtest.h>
-
   // local includes
   #include "src/platform/linux/misc.h"
 
diff --git a/tests/unit/platform/linux/test_kms_plane.cpp b/tests/unit/platform/linux/test_kms_plane.cpp
index bbd1dfc58..77775daf4 100644
--- a/tests/unit/platform/linux/test_kms_plane.cpp
+++ b/tests/unit/platform/linux/test_kms_plane.cpp
@@ -5,12 +5,12 @@
 
 #ifdef __linux__
 
+  // test includes
+  #include "../../../tests_common.h"
+
   // standard includes
   #include <chrono>
 
-  // lib includes
-  #include <gtest/gtest.h>
-
   // local includes
   #include "src/platform/linux/kms_plane.h"
 
diff --git a/tests/unit/platform/linux/test_kmsgrab_cursor_formats.cpp b/tests/unit/platform/linux/test_kmsgrab_cursor_formats.cpp
index 47ae5ff1c..a650e6b0a 100644
--- a/tests/unit/platform/linux/test_kmsgrab_cursor_formats.cpp
+++ b/tests/unit/platform/linux/test_kmsgrab_cursor_formats.cpp
@@ -2,11 +2,15 @@
  * @file tests/unit/platform/linux/test_kmsgrab_cursor_formats.cpp
  * @brief Test KMS cursor format conversion and validation.
  */
+// test includes
+#include "../../../tests_common.h"
+
+// standard includes
 #include <array>
 #include <cstdint>
-#include <gtest/gtest.h>
 
 #ifdef SUNSHINE_BUILD_DRM
+  // lib includes
   #include <drm_fourcc.h>
 
 namespace platf::kms {
diff --git a/tests/unit/platform/linux/test_misc.cpp b/tests/unit/platform/linux/test_misc.cpp
index 1c4c6a409..5e8365df0 100644
--- a/tests/unit/platform/linux/test_misc.cpp
+++ b/tests/unit/platform/linux/test_misc.cpp
@@ -5,15 +5,15 @@
 
 #ifdef __linux__
 
+  // test includes
+  #include "../../../tests_common.h"
+
   // standard includes
   #include <array>
   #include <cstdlib>
   #include <optional>
   #include <string>
 
-  // lib includes
-  #include <gtest/gtest.h>
-
   // local includes
   #include "src/logging.h"
   #include "src/platform/linux/misc.h"
diff --git a/tests/unit/platform/linux/test_wayland.cpp b/tests/unit/platform/linux/test_wayland.cpp
index 1b794fddf..dc3371a59 100644
--- a/tests/unit/platform/linux/test_wayland.cpp
+++ b/tests/unit/platform/linux/test_wayland.cpp
@@ -3,6 +3,9 @@
  * @brief Test Wayland output mode selection.
  */
 #ifdef SUNSHINE_BUILD_WAYLAND
+  // test includes
+  #include "../../../tests_common.h"
+
   // standard includes
   #include <array>
   #include <cerrno>
@@ -25,9 +28,6 @@
   #include <unistd.h>
   #include <xf86drm.h>
 
-  // test includes
-  #include "../../../tests_common.h"
-
   // local includes
   #include <src/platform/linux/wayland.h>
   #ifdef SUNSHINE_BUILD_CUDA
diff --git a/tests/unit/platform/windows/test_nvprefs_undo_data.cpp b/tests/unit/platform/windows/test_nvprefs_undo_data.cpp
index 59721347b..1861999f5 100644
--- a/tests/unit/platform/windows/test_nvprefs_undo_data.cpp
+++ b/tests/unit/platform/windows/test_nvprefs_undo_data.cpp
@@ -11,9 +11,6 @@
   // standard includes
   #include <type_traits>
 
-  // lib includes
-  #include <gtest/gtest.h>
-
   // local includes
   #include "src/platform/windows/nvprefs/undo_data.h"
   #include "src/platform/windows/nvprefs/undo_file.h"
diff --git a/tests/unit/test_constructor_contracts.cpp b/tests/unit/test_constructor_contracts.cpp
index 0926c3cc2..4689abdd2 100644
--- a/tests/unit/test_constructor_contracts.cpp
+++ b/tests/unit/test_constructor_contracts.cpp
@@ -3,6 +3,9 @@
  * @brief Tests for explicit conversions, ownership transfers, and member initialization.
  */
 
+// test includes
+#include "../tests_common.h"
+
 // standard includes
 #include <array>
 #include <functional>
@@ -12,9 +15,6 @@
 #include <utility>
 #include <vector>
 
-// lib includes
-#include <gtest/gtest.h>
-
 // local includes
 #include "src/crypto.h"
 #include "src/move_by_copy.h"
diff --git a/tests/unit/test_crypto.cpp b/tests/unit/test_crypto.cpp
index bb953de70..68e6c9f99 100644
--- a/tests/unit/test_crypto.cpp
+++ b/tests/unit/test_crypto.cpp
@@ -3,14 +3,13 @@
  * @brief Test src/crypto.*.
  */
 // test includes
+#include "../certificate_test_utils.h"
 #include "../tests_common.h"
 
 // lib includes
 #include <openssl/x509.h>
 
 // local includes
-#include "../certificate_test_utils.h"
-
 #include <src/crypto.h>
 
 TEST(CryptoTest, GeneratedCredentialsExposeSubjectAndVerifySignatures) {
diff --git a/tests/unit/test_nvenc_dynamic_factory.cpp b/tests/unit/test_nvenc_dynamic_factory.cpp
index e67be1992..c8f12ba36 100644
--- a/tests/unit/test_nvenc_dynamic_factory.cpp
+++ b/tests/unit/test_nvenc_dynamic_factory.cpp
@@ -4,6 +4,9 @@
  */
 #ifdef _WIN32
 
+  // test includes
+  #include "../tests_common.h"
+
   // standard includes
   #include <array>
   #include <bit>
@@ -12,9 +15,6 @@
   #include <string_view>
   #include <utility>
 
-  // lib includes
-  #include <gtest/gtest.h>
-
   // local includes
   #include "src/nvenc/nvenc_dynamic_factory.h"
 
diff --git a/tests/unit/test_nvenc_utils.cpp b/tests/unit/test_nvenc_utils.cpp
index f59b8428a..12188cfc0 100644
--- a/tests/unit/test_nvenc_utils.cpp
+++ b/tests/unit/test_nvenc_utils.cpp
@@ -4,6 +4,9 @@
  */
 
 #ifdef _WIN32
+  // test includes
+  #include "../tests_common.h"
+
   // standard includes
   #include <array>
   #include <bit>
@@ -13,9 +16,6 @@
   #include <tuple>
   #include <utility>
 
-  // lib includes
-  #include <gtest/gtest.h>
-
   // local includes
   #include "src/nvenc/nvenc_base.h"
   #include "src/nvenc/nvenc_d3d11.h"
diff --git a/tests/unit/test_nvenc_version.cpp b/tests/unit/test_nvenc_version.cpp
index daa39f264..2151290d4 100644
--- a/tests/unit/test_nvenc_version.cpp
+++ b/tests/unit/test_nvenc_version.cpp
@@ -3,13 +3,13 @@
  * @brief Tests for runtime NVENC SDK version selection.
  */
 
+// test includes
+#include "../tests_common.h"
+
 // standard includes
 #include <array>
 #include <cstdint>
 
-// lib includes
-#include <gtest/gtest.h>
-
 // local includes
 #include "src/nvenc/nvenc_version.h"
 
diff --git a/tests/unit/test_nvhttp_client_auth.cpp b/tests/unit/test_nvhttp_client_auth.cpp
index 6cf416dd8..297390793 100644
--- a/tests/unit/test_nvhttp_client_auth.cpp
+++ b/tests/unit/test_nvhttp_client_auth.cpp
@@ -3,6 +3,7 @@
  * @brief Test exact paired-client certificate authorization and persistence.
  */
 
+// test includes
 #include "../certificate_test_utils.h"
 #include "../tests_common.h"
 
diff --git a/tests/unit/test_rtsp.cpp b/tests/unit/test_rtsp.cpp
index ee07040aa..e9b903af6 100644
--- a/tests/unit/test_rtsp.cpp
+++ b/tests/unit/test_rtsp.cpp
@@ -3,6 +3,9 @@
  * @brief Verify RTSP response handlers through their common dispatcher signature.
  */
 
+// test includes
+#include "../tests_common.h"
+
 // standard includes
 #include <array>
 #include <string>
@@ -14,9 +17,6 @@ extern "C" {
 #include <moonlight-common-c/src/Rtsp.h>
 }
 
-// test includes
-#include "../tests_common.h"
-
 // local includes
 #include <src/rtsp.h>
 
diff --git a/tests/unit/test_sync.cpp b/tests/unit/test_sync.cpp
index 7cef9b490..1d45864f3 100644
--- a/tests/unit/test_sync.cpp
+++ b/tests/unit/test_sync.cpp
@@ -3,15 +3,15 @@
  * @brief Regression coverage for synchronized-value lock lifetimes.
  */
 
+// test includes
+#include "../tests_common.h"
+
 // standard includes
 #include <array>
 #include <stdexcept>
 #include <system_error>
 #include <thread>
 
-// lib includes
-#include <gtest/gtest.h>
-
 // local includes
 #include <src/sync.h>
 
diff --git a/tests/unit/test_system_tray.cpp b/tests/unit/test_system_tray.cpp
index 1c779613a..3bb4bddd7 100644
--- a/tests/unit/test_system_tray.cpp
+++ b/tests/unit/test_system_tray.cpp
@@ -5,6 +5,12 @@
 
 // test includes
 #include "../tests_common.h"
+#if defined(SUNSHINE_TRAY) && SUNSHINE_TRAY >= 1
+  #if defined(__linux__) || defined(__APPLE__) || defined(_WIN32)
+    #include "third-party/tray/tests/notification_utils.h"
+    #include "third-party/tray/tests/screenshot_utils.h"
+  #endif
+#endif
 
 // standard includes
 #include <atomic>
@@ -25,21 +31,15 @@
   #if defined(_WIN32) || defined(__APPLE__)
     #include <libvirtualhid/license.hpp>
   #endif
+  #if defined(__linux__) || defined(__APPLE__) || defined(_WIN32)
+    #include <lizardbyte/common/env.h>
+  #endif
 
   // local includes
   #include <src/config.h>
   #include <src/system_tray.h>
   #include <src/thread_safe.h>
 
-  #if defined(__linux__) || defined(__APPLE__) || defined(_WIN32)
-    // lib includes
-    #include <lizardbyte/common/env.h>
-
-    // test includes
-    #include "third-party/tray/tests/notification_utils.h"
-    #include "third-party/tray/tests/screenshot_utils.h"
-  #endif
-
 namespace {
   using namespace std::chrono_literals;
 
diff --git a/tests/unit/test_task_pool.cpp b/tests/unit/test_task_pool.cpp
index 203b8a7a7..6119a063d 100644
--- a/tests/unit/test_task_pool.cpp
+++ b/tests/unit/test_task_pool.cpp
@@ -3,8 +3,8 @@
  * @brief Regression coverage for delayed task lookup over the complete queue.
  */
 
-// lib includes
-#include <gtest/gtest.h>
+// test includes
+#include "../tests_common.h"
 
 // local includes
 #include <src/task_pool.h>
diff --git a/tests/unit/test_thread_safe.cpp b/tests/unit/test_thread_safe.cpp
index 2ec90318c..bc32f9d47 100644
--- a/tests/unit/test_thread_safe.cpp
+++ b/tests/unit/test_thread_safe.cpp
@@ -3,13 +3,13 @@
  * @brief Tests for thread-safe utility types.
  */
 
+// test includes
+#include "../tests_common.h"
+
 // standard includes
 #include <cstdint>
 #include <type_traits>
 
-// lib includes
-#include <gtest/gtest.h>
-
 // local includes
 #include "src/thread_safe.h"