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 以解決此問題。3.10.1 和 3.10.2 中 TIMEOUT 關鍵字的不明確行為未被保留。

XML_OUTPUT_DIR dir

版本 3.18 新增。

如果指定，則參數會與 --gtest_output=xml: 一起傳遞給測試可執行檔。實際檔案名稱與測試目標相同，包括前綴和後綴。這應該用於取代 EXTRA_ARGS --gtest_output=xml，以避免在使用平行測試執行時寫入 XML 結果輸出時發生競爭狀況。

DISCOVERY_MODE

版本 3.18 新增。

提供對 gtest_discover_tests() 執行測試發現的時間的更大控制權。預設情況下，POST_BUILD 設定後建置命令以在建置時執行測試發現。在某些情況下，例如交叉編譯，這種 POST_BUILD 行為是不希望有的。相反，PRE_TEST 將測試發現延遲到測試執行之前。這樣，測試發現發生在目標環境中，測試更有可能找到適當的執行階段相依性。

DISCOVERY_MODE 預設為 CMAKE_GTEST_DISCOVER_TESTS_DISCOVERY_MODE 變數的值，如果呼叫 gtest_discover_tests() 時未傳遞該變數。這提供了一種機制，用於全域選擇偏好的測試發現行為，而無需修改每個呼叫站點。

DISCOVERY_EXTRA_ARGS args...

版本 3.31 新增。

要在發現命令的命令列上傳遞的任何額外引數。

在 3.29 版本中新增：在測試發現和測試執行期間，TEST_LAUNCHER 目標屬性會被採用。

在 3.31 版本中變更：TEST_LAUNCHER 和 CROSSCOMPILING_EMULATOR 目標屬性中的空值會被保留，請參閱政策 CMP0178。