GoogleTest¶
在版本 3.9 中新增。
此模組定義了輔助使用 Google Test 基礎架構的函式。提供了兩種新增測試的機制。gtest_add_tests() 已經存在一段時間了，最初是透過 find_package(GTest)。 gtest_discover_tests() 是在 CMake 3.10 中引入的。
（較舊的）gtest_add_tests() 掃描原始碼檔案以識別測試。這通常是有效的，但有一些注意事項，包括在交叉編譯環境中，並且可以更方便地在測試中設定其他屬性。然而，它對參數化測試的處理不太全面，並且需要重新執行 CMake 以檢測測試清單的變更。
（較新的）gtest_discover_tests() 透過要求已編譯的測試可執行檔列舉其測試來發現測試。這樣更穩健，並能更好地處理參數化測試，並且在測試變更時不需要重新執行 CMake。然而，它可能無法在交叉編譯環境中運作，並且設定測試屬性不太方便。
更多詳細資訊可以在各個函式的文件中找到。
這兩個指令旨在取代使用 add_test() 來註冊測試，並且會為每個 Google Test 測試案例建立單獨的 CTest 測試。請注意，在某些情況下，這種方式效率較低，因為在同一個執行個體中執行的多個測試案例無法共用共同的設定和拆解邏輯。然而，它為 CTest 提供了更精細的通過/失敗資訊，這通常被認為更有益。預設情況下，CTest 測試名稱與 Google Test 名稱相同（即 suite.testcase）；另請參閱 TEST_PREFIX 和 TEST_SUFFIX。
- gtest_add_tests¶
透過掃描原始碼中的 Google Test 巨集，自動使用 CTest 新增測試
gtest_add_tests(TARGET target [SOURCES src1...] [EXTRA_ARGS args...] [WORKING_DIRECTORY dir] [TEST_PREFIX prefix] [TEST_SUFFIX suffix] [SKIP_DEPENDENCY] [TEST_LIST outVar] )gtest_add_tests嘗試透過掃描原始碼檔案來識別測試。雖然這通常是有效的，但它僅使用基本的正規表示式匹配，這可能會被非典型的測試宣告所擊敗，並且無法完全「分割」參數化測試。此外，它要求重新執行 CMake 以發現任何新新增、移除或重新命名的測試（預設情況下，這表示當任何測試原始碼檔案變更時會重新執行 CMake，但請參閱SKIP_DEPENDENCY）。然而，它的優點是在 CMake 時間宣告測試，這在一定程度上簡化了在測試中設定其他屬性，並且始終在交叉編譯環境中運作。選項如下：
TARGET target指定 Google Test 可執行檔，該執行檔必須是已知的 CMake 可執行檔目標。CMake 將在執行測試時替換已建置的可執行檔位置。
SOURCES src1...如果提供此選項，則只會掃描列出的檔案以尋找測試案例。如果未提供此選項，將使用指定的
target的SOURCES屬性來取得原始碼清單。EXTRA_ARGS args...要傳遞給每個測試案例的任何額外命令列引數。
在 3.31 版本中變更：保留
args...中的空值，請參閱CMP0178。WORKING_DIRECTORY dir指定執行已發現測試案例的目錄。如果未提供此選項，則使用目前的二進位檔目錄。
TEST_PREFIX prefix指定要附加到每個已發現測試案例名稱的
prefix。當相同的原始碼檔案在多次呼叫gtest_add_test()中使用，但使用不同的EXTRA_ARGS時，這會很有用。TEST_SUFFIX suffix與
TEST_PREFIX類似，不同之處在於suffix會附加到每個已發現測試案例的名稱。可以指定TEST_PREFIX和TEST_SUFFIX。SKIP_DEPENDENCY通常，此函式會建立一個相依性，如果正在掃描的任何原始碼變更，將會導致重新執行 CMake。這是為了確保已發現的測試清單已更新。如果不希望這種行為（在實際撰寫測試案例時可能會發生這種情況），可以使用此選項來防止新增相依性。
TEST_LIST outVar名為
outVar的變數將會在使用範圍中填入已發現的測試案例清單。這允許呼叫者執行操作，例如操作已發現測試的測試屬性。
在 3.31 版本中變更：保留
TEST_LAUNCHER和CROSSCOMPILING_EMULATOR目標屬性中的空值，請參閱原則CMP0178。用法範例
include(GoogleTest) add_executable(FooTest FooUnitTest.cxx) gtest_add_tests(TARGET FooTest TEST_SUFFIX .noArgs TEST_LIST noArgsTests ) gtest_add_tests(TARGET FooTest EXTRA_ARGS --someArg someValue TEST_SUFFIX .withArgs TEST_LIST withArgsTests ) set_tests_properties(${noArgsTests} PROPERTIES TIMEOUT 10) set_tests_properties(${withArgsTests} PROPERTIES TIMEOUT 20)
為了向後相容性，也支援以下形式
gtest_add_tests(exe args files...)
exe測試可執行檔的路徑或 CMake 目標的名稱。
args要傳遞給可執行檔的額外引數的 ;-list。整個清單必須作為單一引數傳遞。將其括在引號中，或傳遞
""以表示沒有引數。files...要搜尋測試和測試夾具的原始碼檔案清單。或者，使用
AUTO來指定exe是 CMake 可執行檔目標的名稱，其原始碼應被掃描。
include(GoogleTest) set(FooTestArgs --foo 1 --bar 2) add_executable(FooTest FooUnitTest.cxx) gtest_add_tests(FooTest "${FooTestArgs}" AUTO)
- gtest_discover_tests¶
透過查詢已編譯的測試可執行檔以取得可用測試，自動使用 CTest 新增測試
gtest_discover_tests(target [EXTRA_ARGS args...] [WORKING_DIRECTORY dir] [TEST_PREFIX prefix] [TEST_SUFFIX suffix] [TEST_FILTER expr] [NO_PRETTY_TYPES] [NO_PRETTY_VALUES] [PROPERTIES name1 value1...] [TEST_LIST var] [DISCOVERY_TIMEOUT seconds] [XML_OUTPUT_DIR dir] [DISCOVERY_MODE <POST_BUILD|PRE_TEST>] [DISCOVERY_EXTRA_ARGS args...] )在版本 3.10 中新增。
gtest_discover_tests()在測試可執行檔上設定建置後或測試前指令，透過剖析使用--gtest_list_tests引數執行測試可執行檔的輸出，來產生測試清單。與gtest_add_tests()的原始碼剖析方法相比，這可確保取得完整的測試清單，包括參數化測試的實例。由於測試探索發生在建置或測試時，因此當測試清單變更時，不需要重新執行 CMake。然而，它要求正確設定CROSSCOMPILING_EMULATOR，以便在交叉編譯環境中運作。此外，設定測試的屬性有點不方便，因為測試在 CMake 時間不可用。可以使用
PROPERTIES選項將其他測試屬性指派給整個測試集。如果需要更精細的測試控制，可以使用TEST_INCLUDE_FILES目錄屬性，透過外部 CTest 腳本提供自訂內容。已探索的測試集可透過<target>_TESTS變數存取此類腳本（請參閱下面的TEST_LIST選項以了解更多討論和限制）。選項如下：
target指定 Google Test 可執行檔，該執行檔必須是已知的 CMake 可執行檔目標。CMake 將在執行測試時替換已建置的可執行檔位置。
EXTRA_ARGS args...要傳遞給每個測試案例的任何額外命令列引數。
在版本 3.31 中變更：
args...中的空值會被保留，請參閱CMP0178。WORKING_DIRECTORY dir指定執行已發現測試案例的目錄。如果未提供此選項，則使用目前的二進位檔目錄。
TEST_PREFIX prefix指定一個
prefix，加在每個發現的測試案例名稱的前面。當同一個測試執行檔在多次調用gtest_discover_tests()時使用，但具有不同的EXTRA_ARGS時，這會很有用。TEST_SUFFIX suffix與
TEST_PREFIX類似，不同之處在於suffix會附加到每個已發現測試案例的名稱。可以指定TEST_PREFIX和TEST_SUFFIX。TEST_FILTER expr在版本 3.22 中新增。
在測試探索期間，作為
--gtest_filter參數傳遞的過濾表達式。請注意，該表達式是一種基於萬用字元的格式，與 gtest 使用的原始測試名稱進行比對。對於型別或值參數化測試，這些名稱可能與 ctest 使用的可能經過美化的測試名稱不同。NO_PRETTY_TYPES預設情況下，型別參數化測試的型別索引會被 CTest 測試名稱中的實際型別名稱取代。如果這種行為不理想（例如，因為型別名稱很笨拙），此選項將會抑制此行為。
NO_PRETTY_VALUES預設情況下，值參數化測試的值索引會被 CTest 測試名稱中的實際值取代。如果這種行為不理想（例如，因為值字串很笨拙），此選項將會抑制此行為。
PROPERTIES name1 value1...指定要在此次調用
gtest_discover_tests()發現的所有測試中設定的額外屬性。TEST_LIST var將測試列表儲存在變數
var中，而不是預設的<target>_TESTS。當同一個測試執行檔在多次調用gtest_discover_tests()時使用時，這會很有用。請注意，此變數僅在 CTest 中可用。由於 CMake 解析規則的限制，任何名稱中包含方括號的測試都會從儲存在此變數中的測試列表中省略。不過，這些測試仍然會像往常一樣由
ctest定義和執行。DISCOVERY_TIMEOUT num在版本 3.10.3 中新增。
指定 CMake 將等待測試列舉可用測試的時間長度（以秒為單位）。如果測試時間超過此值，探索（以及您的建置）將會失敗。大多數測試執行檔會很快列舉其測試，但在某些特殊情況下，測試可能需要更長的逾時時間。預設值為 5。另請參閱
execute_process()的TIMEOUT選項。注意
在 CMake 版本 3.10.1 和 3.10.2 中，此選項稱為
TIMEOUT。這與TIMEOUT測試屬性衝突，而測試屬性是通常會使用PROPERTIES關鍵字設定的常用屬性之一，通常會導致合法但不想要的行為。為了解決這個問題，在 CMake 3.10.3 中，關鍵字被變更為DISCOVERY_TIMEOUT。TIMEOUT關鍵字在 3.10.1 和 3.10.2 中的不明確行為並未保留。XML_OUTPUT_DIR dir在版本 3.18 中新增。
如果指定，此參數會與
--gtest_output=xml:一起傳遞到測試執行檔。實際的檔案名稱與測試目標相同，包含前綴和後綴。當使用平行測試執行時，為了避免寫入 XML 結果輸出時發生競爭條件，應使用此選項，而不是EXTRA_ARGS --gtest_output=xml。DISCOVERY_MODE在版本 3.18 中新增。
提供對
gtest_discover_tests()何時執行測試探索的更大控制權。預設情況下，POST_BUILD會設定一個後建置命令，在建置時執行測試探索。在某些情況下，例如交叉編譯，這種POST_BUILD行為是不理想的。相比之下，PRE_TEST會將測試探索延遲到測試執行之前。這樣，測試探索會在目標環境中進行，而測試在該環境中有更好的機會找到適當的執行階段相依性。如果在調用
gtest_discover_tests()時未傳遞DISCOVERY_MODE，則其預設為CMAKE_GTEST_DISCOVER_TESTS_DISCOVERY_MODE變數的值。這提供了一種全域選擇偏好的測試探索行為的機制，而無需修改每個調用位置。DISCOVERY_EXTRA_ARGS args...在版本 3.31 中新增。
在探索命令的命令列上傳遞的任何額外參數。
在版本 3.29 中新增：在測試探索和測試執行期間，會採用
TEST_LAUNCHER目標屬性。在版本 3.31 中變更：
TEST_LAUNCHER和CROSSCOMPILING_EMULATOR目標屬性中的空值會被保留，請參閱政策CMP0178。