ctest(1)¶

概要 ¶

Run Tests
 ctest [<options>] [--test-dir <path-to-build>]

Build and Test Mode
 ctest --build-and-test <path-to-source> <path-to-build>
       --build-generator <generator> [<options>...]
      [--build-options <opts>...]
      [--test-command <command> [<args>...]]

Dashboard Client
 ctest -D <dashboard>         [-- <dashboard-options>...]
 ctest -M <model> -T <action> [-- <dashboard-options>...]
 ctest -S <script>            [-- <dashboard-options>...]
 ctest -SP <script>           [-- <dashboard-options>...]

View Help
 ctest --help[-<topic>]

描述 ¶

ctest 執行檔是 CMake 測試驅動程式。為使用 enable_testing() 和 add_test() 命令的專案建立的 CMake 產生的建置樹狀結構具有測試支援。此程式將執行測試並報告結果。

執行測試 ¶

--preset <preset>, --preset=<preset>¶: 使用測試預設集來指定測試選項。專案二進制目錄會從 configurePreset 金鑰推斷。目前的工作目錄必須包含 CMake 預設集檔案。請參閱 preset 以取得更多詳細資訊。

--list-presets¶: 列出可用的測試預設集。目前的工作目錄必須包含 CMake 預設集檔案。

-C <cfg>, --build-config <cfg>¶

選擇要測試的配置。

某些 CMake 產生的建置樹狀結構可以在同一個樹狀結構中有多個建置配置。此選項可用於指定應測試哪一個。範例配置為 Debug 和 Release。

--progress¶

啟用來自測試的簡短進度輸出。

當 ctest 的輸出直接傳送到終端機時，會透過更新同一行來報告測試集的進度，而不是在新行上印出每個測試的開始和結束訊息。這可以顯著減少測試輸出的冗長程度。測試完成訊息仍然會在自己的行上輸出，以用於失敗的測試，並且最終測試摘要也仍將被記錄。

也可以透過設定環境變數 CTEST_PROGRESS_OUTPUT 來啟用此選項。

-V, --verbose¶

啟用來自測試的詳細輸出。

測試輸出通常會被抑制，並且僅顯示摘要資訊。此選項將顯示所有測試輸出。

-VV, --extra-verbose¶

啟用來自測試的更詳細輸出。

測試輸出通常會被抑制，並且僅顯示摘要資訊。此選項將顯示更多測試輸出。

--debug¶

顯示 CTest 的更詳細內部資訊。

此功能將產生大量輸出，主要用於偵錯儀表板問題。

--output-on-failure¶: 如果測試失敗，則輸出測試程式輸出的任何內容。也可以透過設定 CTEST_OUTPUT_ON_FAILURE 環境變數來啟用此選項

--stop-on-failure¶: 在發生第一個失敗時停止執行測試。

-F¶

啟用容錯移轉。

此選項允許 CTest 恢復先前中斷的測試集執行。如果未發生中斷，則 -F 選項將不會有任何效果。

-j [<level>], --parallel [<level>]¶

並行執行測試，可選擇限制為給定的並行層級。

版本 3.29 新增: <level> 可以省略，或 0，在這種情況下

在 Job Server 整合下，並行性受到可用工作權杖的限制。
否則，如果省略該值，則並行性受處理器數量或 2 的限制，以較大者為準。
否則，如果該值為 0，則並行性不受限制。

此選項也可以由 CTEST_PARALLEL_LEVEL 環境變數指定。

此選項可以與 PROCESSORS 測試屬性一起使用。請參閱標籤與子專案摘要。

--resource-spec-file <file>¶

執行啟用資源分配的 CTest，並使用資源規格檔案，該檔案在 <file> 中指定。

當 ctest 作為儀表板用戶端執行時，這會設定 CTest 測試步驟的 ResourceSpecFile 選項。

--test-load <level>¶

在並行執行測試時 (例如使用 -j)，嘗試不要在測試可能導致 CPU 負載超過給定閾值時啟動測試。

當 ctest 作為儀表板用戶端執行時，這會設定 CTest 測試步驟的 TestLoad 選項。

-Q, --quiet¶

使 CTest 靜音。

此選項將抑制所有輸出。如果指定了 --output-log，則仍將產生輸出日誌檔。如果指定了 --quiet，則會忽略諸如 --verbose、--extra-verbose 和 --debug 等選項。

-O <file>, --output-log <file>¶

輸出到日誌檔。

此選項告知 CTest 將其所有輸出寫入 <file> 日誌檔。

--output-junit <file>¶

版本 3.21 新增。

以 JUnit 格式寫入測試結果。

此選項告知 CTest 以 JUnit XML 格式將測試結果寫入 <file>。如果 <file> 已經存在，它將被覆寫。如果使用 -S 選項來執行儀表板腳本，請改用 ctest_test() 命令的 OUTPUT_JUNIT 關鍵字。

-N, --show-only[=<format>]¶

停用測試的實際執行。

此選項告知 CTest 列出將要執行的測試，但實際上不執行它們。與 -R 和 -E 選項結合使用很有用。

版本 3.14 新增: --show-only 選項接受 <format> 值。

<format> 可以是以下值之一。

human
人類友善的輸出。不保證穩定。這是預設值。

json-v1
以 JSON 格式傾印測試資訊。請參閱顯示為 JSON 物件模型。

-L <regex>, --label-regex <regex>¶

執行標籤與規則運算式匹配的測試，如 string(REGEX) 下所述。

此選項告知 CTest 僅執行標籤與給定規則運算式匹配的測試。當給定多個 -L 選項時，只有在每個規則運算式都至少匹配測試的一個標籤時，才會執行測試 (即多個 -L 標籤形成 AND 關係)。請參閱標籤匹配。

-R <regex>, --tests-regex <regex>¶

執行與規則運算式匹配的測試。

此選項告知 CTest 僅執行名稱與給定規則運算式匹配的測試。

-E <regex>, --exclude-regex <regex>¶

排除與規則運算式匹配的測試。

此選項告知 CTest 不要執行名稱與給定規則運算式匹配的測試。

-LE <regex>, --label-exclude <regex>¶

排除標籤與規則運算式匹配的測試。

此選項告知 CTest 不要執行標籤與給定規則運算式匹配的測試。當給定多個 -LE 選項時，只有在每個規則運算式都至少匹配測試的一個標籤時，才會排除測試 (即多個 -LE 標籤形成 AND 關係)。請參閱標籤匹配。

--tests-from-file <filename>¶

版本 3.29 新增。

執行給定檔案中列出的測試。

此選項告知 CTest 執行給定檔案中列出的測試。該檔案每行必須包含一個確切的測試名稱。不完全匹配任何測試名稱的行將被忽略。此選項可以與其他選項結合使用，例如 -R、-E、-L 或 -LE。

--exclude-from-file <filename>¶

版本 3.29 新增。

排除給定檔案中列出的測試。

此選項告知 CTest 不要執行給定檔案中列出的測試。該檔案每行必須包含一個確切的測試名稱。不完全匹配任何測試名稱的行將被忽略。此選項可以與其他選項結合使用，例如 -R、-E、-L 或 -LE。

-FA <regex>, --fixture-exclude-any <regex>¶

排除與 <regex> 匹配的 fixture，使其不會自動將任何測試新增到測試集。

如果要在執行的測試集中的測試需要特定的 fixture，則該 fixture 的設定和清理測試通常會自動新增到測試集中。此選項可防止為與 <regex> 匹配的 fixture 新增設定或清理測試。請注意，所有其他 fixture 行為都將保留，包括測試相依性和跳過具有 fixture 設定測試失敗的測試。

-FS <regex>, --fixture-exclude-setup <regex>¶: 與 -FA 相同，但僅排除匹配的設定測試。

-FC <regex>, --fixture-exclude-cleanup <regex>¶: 與 -FA 相同，但僅排除匹配的清理測試。

-I [Start,End,Stride,test#,test#|Test file], --tests-information¶

依編號執行特定數量的測試。

此選項使 CTest 執行從編號 Start 開始、到編號 End 結束並以 Stride 遞增的測試。在 Stride 之後的任何其他數字都被視為個別測試編號。Start、End 或 Stride 可以為空。或者，可以給定一個檔案，其中包含與命令列相同的語法。

-U, --union¶

取 -I 和 -R 的聯集。

當同時指定 -R 和 -I 時，預設情況下會執行測試的交集。透過指定 -U，將改為執行測試的聯集。

--rerun-failed¶

僅執行先前失敗的測試。

此選項告知 CTest 僅執行在其先前執行期間失敗的測試。當指定此選項時，CTest 會忽略所有其他旨在修改要執行的測試列表的選項 (-L、-R、-E、-LE、-I 等)。如果 CTest 執行且沒有測試失敗，則後續使用 --rerun-failed 選項呼叫 CTest 將執行最近失敗的測試集 (如果有的話)。

--repeat <mode>:<n>¶

根據給定的 <mode> 重複執行測試最多 <n> 次。模式為

until-fail: 要求每個測試執行 <n> 次而沒有失敗才能通過。這對於在測試案例中尋找零星失敗很有用。
until-pass: 允許每個測試執行最多 <n> 次才能通過。如果測試因任何原因失敗，則重複測試。這對於容忍測試案例中的零星失敗很有用。
after-timeout: 允許每個測試執行最多 <n> 次才能通過。僅當測試超時時才重複測試。這對於容忍繁忙機器上測試案例中的零星超時很有用。

--repeat-until-fail <n>¶: 等效於 --repeat until-fail:<n>。

--max-width <width>¶

設定要輸出的測試名稱的最大寬度。

設定要在輸出中顯示的每個測試名稱的最大寬度。這允許使用者加寬輸出，以避免剪切測試名稱，這可能會非常煩人。

--interactive-debug-mode <0|1>¶

停用 (0) 或啟用 (1) 互動式偵錯模式。

此選項使 CTest 在互動模式或非互動模式下執行測試。在儀表板模式 (Experimental、Nightly、Continuous) 下，預設為非互動模式。在非互動模式下，將設定環境變數 DASHBOARD_TEST_FROM_CTEST。

互動模式允許 Windows 錯誤報告 (WER) 顯示偵錯彈出視窗並建立核心轉儲。若要在測試中啟用核心轉儲，請使用互動模式，並遵循 Windows 文件中關於收集使用者模式轉儲的說明。

在版本 4.0 中變更: Windows 錯誤報告 (WER) 在互動模式下啟用，因此測試程序可能會顯示偵錯彈出視窗並建立核心轉儲。這是透過更新 libuv 實現的。

在版本 3.11 中變更: Windows 錯誤報告 (WER) 在互動和非互動模式下都已停用，因此測試程序不會顯示彈出視窗或建立核心轉儲。這是由於使用 libuv 啟動測試程序。

--no-label-summary¶

停用標籤的計時摘要資訊。

此選項告知 CTest 不要印出與執行的測試相關聯的每個標籤的摘要資訊。如果測試上沒有標籤，則不會印出任何額外資訊。

請參閱標籤與子專案摘要。

--no-subproject-summary¶

停用子專案的計時摘要資訊。

此選項告知 CTest 不要印出與執行的測試相關聯的每個子專案的摘要資訊。如果測試上沒有子專案，則不會印出任何額外資訊。

請參閱標籤與子專案摘要。

--test-dir <dir>¶: 版本 3.20 新增。

指定要在其中尋找測試的目錄，通常是 CMake 專案建置目錄。如果未指定，則使用目前目錄。

--test-output-size-passed <size>¶: 版本 3.4 新增。

限制通過測試的輸出大小為 <size> 位元組。

--test-output-size-failed <size>¶: 版本 3.4 新增。

限制失敗測試的輸出大小為 <size> 位元組。

--test-output-truncation <mode>¶: 版本 3.24 新增。

達到最大輸出大小後，截斷測試輸出的 tail (預設)、middle 或 head。

--overwrite¶

覆寫 CTest 組態選項。

預設情況下，CTest 使用來自組態檔的組態選項。此選項將覆寫組態選項。

--force-new-ctest-process¶: 已忽略。此選項曾經停用針對執行 ctest 本身的測試的現已移除的最佳化。

--schedule-random¶

使用隨機順序排程測試。

此選項將以隨機順序執行測試。它通常用於偵測測試套件中的隱含依賴關係。

--submit-index¶: 舊版選項，用於舊的 Dart2 儀表板伺服器功能。請勿使用。

--timeout <seconds>¶

設定預設測試逾時。

此選項有效地為所有尚未透過 TIMEOUT 屬性設定逾時的測試設定逾時。

--stop-time <time>¶

設定所有測試應停止運行的時間。

設定所有測試應逾時的實際日期時間。範例：7:00:00 -0400。接受 curl 日期剖析器可理解的任何時間格式。如果未指定時區，則假定為本地時間。

--print-labels¶

列印所有可用的測試標籤。

此選項不會運行任何測試，它只會列印與測試集關聯的所有標籤的清單。

--no-tests=<action>¶

將找不到測試視為錯誤 (當 <action> 設定為 error 時) 或忽略它 (當 <action> 設定為 ignore 時)。

如果找不到任何測試，CTest 的預設行為是始終記錄錯誤訊息，但僅在腳本模式下傳回錯誤代碼。此選項透過在找不到測試時傳回錯誤代碼或忽略它來統一 CTest 的行為。

版本 3.26 新增。

此選項也可以透過設定 CTEST_NO_TESTS_ACTION 環境變數來設定。

查看說明 ¶

若要列印版本詳細資訊或 CMake 文件中選定的頁面，請使用下列選項之一

-version [<file>], --version [<file>], /V [<file>]¶: 顯示程式名稱/版本標題並退出。輸出會列印到指定的 <file> (如果已給定)。

-h, -H, --help, -help, -usage, /?¶

列印用法資訊並退出。

用法說明基本命令列介面及其選項。

--help <keyword> [<file>]¶

列印單一 CMake 關鍵字的說明。

<keyword> 可以是屬性、變數、命令、策略、產生器或模組。

以人類可讀的文字格式列印 <keyword> 的相關手冊條目。輸出會列印到指定的 <file> (如果已給定)。

變更於版本 3.28: 在 CMake 3.28 之前，此選項僅支援命令名稱。

--help-full [<file>]¶

列印所有說明手冊並退出。

所有手冊都以人類可讀的文字格式列印。輸出會列印到指定的 <file> (如果已給定)。

--help-manual <man> [<file>]¶

列印單一說明手冊並退出。

指定的手冊以人類可讀的文字格式列印。輸出會列印到指定的 <file> (如果已給定)。

--help-manual-list [<file>]¶

列出可用的說明手冊並退出。

清單包含所有可透過使用 --help-manual 選項後接手冊名稱來取得說明的手冊。輸出會列印到指定的 <file> (如果已給定)。

--help-command <cmd> [<file>]¶

列印單一命令的說明並退出。

以人類可讀的文字格式列印 cmake-commands(7) 手冊中 <cmd> 的條目。輸出會列印到指定的 <file> (如果已給定)。

--help-command-list [<file>]¶

列出可用的命令說明並退出。

清單包含所有可透過使用 --help-command 選項後接命令名稱來取得說明的命令。輸出會列印到指定的 <file> (如果已給定)。

--help-commands [<file>]¶

列印 cmake-commands 手冊並退出。

以人類可讀的文字格式列印 cmake-commands(7) 手冊。輸出會列印到指定的 <file> (如果已給定)。

--help-module <mod> [<file>]¶

列印單一模組的說明並退出。

以人類可讀的文字格式列印 cmake-modules(7) 手冊中 <mod> 的條目。輸出會列印到指定的 <file> (如果已給定)。

--help-module-list [<file>]¶

列出可用的模組說明並退出。

清單包含所有可透過使用 --help-module 選項後接模組名稱來取得說明的模組。輸出會列印到指定的 <file> (如果已給定)。

--help-modules [<file>]¶

列印 cmake-modules 手冊並退出。

以人類可讀的文字格式列印 cmake-modules(7) 手冊。輸出會列印到指定的 <file> (如果已給定)。

--help-policy <cmp> [<file>]¶

列印單一策略的說明並退出。

以人類可讀的文字格式列印 cmake-policies(7) 手冊中 <cmp> 的條目。輸出會列印到指定的 <file> (如果已給定)。

--help-policy-list [<file>]¶

列出可用的策略說明並退出。

清單包含所有可透過使用 --help-policy 選項後接策略名稱來取得說明的策略。輸出會列印到指定的 <file> (如果已給定)。

--help-policies [<file>]¶

列印 cmake-policies 手冊並退出。

以人類可讀的文字格式列印 cmake-policies(7) 手冊。輸出會列印到指定的 <file> (如果已給定)。

--help-property <prop> [<file>]¶

列印單一屬性的說明並退出。

以人類可讀的文字格式列印 cmake-properties(7) 手冊中 <prop> 的條目。輸出會列印到指定的 <file> (如果已給定)。

--help-property-list [<file>]¶

列出可用的屬性說明並退出。

清單包含所有可透過使用 --help-property 選項後接屬性名稱來取得說明的屬性。輸出會列印到指定的 <file> (如果已給定)。

--help-properties [<file>]¶

列印 cmake-properties 手冊並退出。

以人類可讀的文字格式列印 cmake-properties(7) 手冊。輸出會列印到指定的 <file> (如果已給定)。

--help-variable <var> [<file>]¶

列印單一變數的說明並退出。

以人類可讀的文字格式列印 cmake-variables(7) 手冊中 <var> 的條目。輸出會列印到指定的 <file> (如果已給定)。

--help-variable-list [<file>]¶

列出可用的變數說明並退出。

清單包含所有可透過使用 --help-variable 選項後接變數名稱來取得說明的變數。輸出會列印到指定的 <file> (如果已給定)。

--help-variables [<file>]¶

列印 cmake-variables 手冊並退出。

以人類可讀的文字格式列印 cmake-variables(7) 手冊。輸出會列印到指定的 <file> (如果已給定)。

標籤匹配 ¶

測試可以附加標籤。可以透過篩選標籤，將測試包含或排除在測試運行之外。每個個別的篩選器都是應用於附加到測試的標籤的正規表示式。

當使用 -L 時，為了將測試包含在測試運行中，每個正規表示式都必須匹配至少一個標籤。使用多個 -L 選項表示「匹配所有這些」。

-LE 選項的工作方式與 -L 完全相同，但排除測試而不是包含測試。如果每個正規表示式都匹配至少一個標籤，則排除測試。

如果測試沒有附加任何標籤，則 -L 永遠不會包含該測試，而 -LE 永遠不會排除該測試。作為帶有標籤的測試範例，請考慮五個測試，並帶有以下標籤

test1 具有標籤 tuesday 和 production
test2 具有標籤 tuesday 和 test
test3 具有標籤 wednesday 和 production
test4 具有標籤 wednesday
test5 具有標籤 friday 和 test

使用 -L tuesday -L test 運行 ctest 將選擇 test2，它同時具有這兩個標籤。使用 -L test 運行 CTest 將選擇 test2 和 test5，因為它們都具有與該正規表示式匹配的標籤。

由於匹配適用於正規表示式，請注意使用 -L es 運行 CTest 將匹配所有五個測試。若要同時選擇 tuesday 和 wednesday 測試，請使用單個正規表示式來匹配它們中的任何一個，例如 -L "tue|wed"。

標籤和子專案摘要 ¶

CTest 列印與運行的測試關聯的每個 LABEL 和子專案的時間摘要資訊。標籤時間摘要將不包含映射到子專案的標籤。

版本 3.22 新增: 在測試執行期間動態新增的標籤也會在時間摘要中報告。請參閱其他標籤。

當設定 PROCESSORS 測試屬性時，CTest 將在標籤和子專案摘要中顯示加權測試時間結果。時間以 sec * proc 而不是僅以 sec 報告。

每個標籤或子專案 j 報告的加權時間摘要計算為

Weighted Time Summary for Label/Subproject j =
    sum(raw_test_time[j,i] * num_processors[j,i], i=1...num_tests[j])

for labels/subprojects j=1...total

其中

raw_test_time[j,i]：j 標籤或子專案的第 i 個測試的實際時間
num_processors[j,i]：CTest PROCESSORS 屬性對於 j 標籤或子專案的第 i 個測試的值
num_tests[j]：與 j 標籤或子專案關聯的測試數量
total：至少運行一個測試的標籤或子專案的總數

因此，每個標籤或子專案的加權時間摘要表示 CTest 給予運行每個標籤或子專案的測試的時間量，並且在與其他標籤或子專案比較時，可以很好地表示每個標籤或子專案的測試的總費用。

例如，如果 SubprojectA 顯示 100 sec*proc，而 SubprojectB 顯示 10 sec*proc，則 CTest 分配了大約 10 倍的 CPU/核心時間來運行 SubprojectA 的測試，而不是 SubprojectB 的測試 (例如，因此，如果要花費精力來降低整個專案的測試套件的成本，那麼降低 SubprojectA 的測試套件的成本可能會比降低 SubprojectB 的測試套件的成本產生更大的影響)。

建置和測試模式 ¶

CTest 提供命令列簽章來配置 (即運行 cmake)、建置和/或執行測試

ctest --build-and-test <path-to-source> <path-to-build>
      --build-generator <generator>
      [<options>...]
      [--build-options <opts>...]
      [--test-command <command> [<args>...]]

配置和測試步驟是可選的。此命令列的引數是原始碼和二進制目錄。--build-generator 選項必須提供才能使用 --build-and-test。如果指定了 --test-command，則將在建置完成後運行它。影響此模式的其他選項包括

--build-and-test¶: 切換到建置和測試模式。

--build-target¶

指定要建置的特定目標。可以多次給定具有不同目標的選項，在這種情況下，每個目標都會依序建置。在建置每個目標之前，將執行清理，除非給定 --build-noclean 選項。

如果未指定 --build-target，則會建置 all 目標。

--build-nocmake¶

運行建置，而無需先運行 cmake。

跳過 cmake 步驟。

--build-run-dir¶

指定程式運行的目錄。

程式編譯後所在的目錄。

--build-two-config¶: 運行 CMake 兩次。

--build-exe-dir¶: 指定可執行檔的目錄。

--build-generator¶: 指定要使用的產生器。請參閱 cmake-generators(7) 手冊。

--build-generator-platform¶: 指定產生器特定的平台。

--build-generator-toolset¶: 指定產生器特定的工具集。

--build-project¶: 指定要建置的專案名稱。

--build-makeprogram¶: 指定 CMake 在配置和建置專案時要使用的明確 make 程式。僅適用於基於 Make 和 Ninja 的產生器。

--build-noclean¶: 跳過 make clean 步驟。

--build-config-sample¶: 用於確定應使用的組態的範例可執行檔。例如 Debug、Release 等。

--build-options¶: 用於配置建置的額外選項 (即用於 CMake，而不是用於建置工具)。請注意，如果指定了此選項，則 --build-options 關鍵字及其引數必須是命令列上給出的最後一個選項，但 --test-command 除外。

--test-command¶: 使用 --build-and-test 選項來作為測試步驟執行的命令。在此關鍵字後面的所有參數都將被視為測試命令行的一部分，因此它必須是給定的最後一個選項。

--test-timeout¶: 時間限制，以秒為單位

儀表板客戶端 ¶

CTest 可以作為 CDash 軟體品質儀表板應用程式的客戶端運作。作為儀表板客戶端，CTest 執行一系列步驟來配置、建置和測試軟體，然後將結果提交到 CDash 伺服器。用於提交到 CDash 的命令行簽名是

ctest -D <dashboard>         [-- <dashboard-options>...]
ctest -M <model> -T <action> [-- <dashboard-options>...]
ctest -S <script>            [-- <dashboard-options>...]
ctest -SP <script>           [-- <dashboard-options>...]

儀表板客戶端的選項包括

-D <dashboard>, --dashboard <dashboard>¶

執行儀表板測試。

此選項告知 CTest 作為 CDash 客戶端並執行儀表板測試。所有測試都是 <Mode><Test>，其中 <Mode> 可以是 Experimental、Nightly 和 Continuous，而 <Test> 可以是 Start、Update、Configure、Build、Test、Coverage 和 Submit。

如果 <dashboard> 不是已識別的 <Mode><Test> 值之一，則這將被視為變數定義（請參閱下面的儀表板選項）。

-M <model>, --test-model <model>¶

設定儀表板的模型。

此選項告知 CTest 作為 CDash 客戶端，其中 <model> 可以是 Experimental、Nightly 和 Continuous。組合 -M 和 -T 類似於 -D。

-T <action>, --test-action <action>¶

設定要執行的儀表板動作。

此選項告知 CTest 作為 CDash 客戶端並執行某些動作，例如 start、build、test 等。請參閱儀表板客戶端步驟以獲取完整的動作列表。組合 -M 和 -T 類似於 -D。

-S <script>, --script <script>¶

為組態執行儀表板。

此選項告知 CTest 載入組態腳本，該腳本設定許多參數，例如二進制和原始碼目錄。然後 CTest 將執行建立和執行儀表板所需的操作。此選項基本上設定儀表板，然後使用適當的選項執行 ctest -D。

-SP <script>, --script-new-process <script>¶

為組態執行儀表板。

此選項執行與 -S 相同的操作，但它將在單獨的進程中執行這些操作。這主要在腳本可能會修改環境，而您不希望修改後的環境影響其他 -S 腳本的情況下很有用。

可用的 <dashboard-options> 如下

-D <var>:<type>=<value>¶

為腳本模式定義變數。

在命令行中傳入變數值。與 -S 結合使用，以將變數值傳遞給儀表板腳本。僅當 -D 後面的值與任何已知的儀表板類型都不匹配時，才會嘗試將 -D 參數解析為變數值。

--group <group>¶

指定您要將結果提交到的群組

將儀表板提交到指定的群組，而不是預設群組。預設情況下，儀表板提交到 Nightly、Experimental 或 Continuous 群組，但通過指定此選項，群組可以是任意的。

這取代了已棄用的選項 --track。儘管名稱已更改，但其行為保持不變。

-A <file>, --add-notes <file>¶

提交時新增註解檔案。

此選項告知 CTest 在提交儀表板時包含註解檔案。

--tomorrow-tag¶

Nightly 或 Experimental 以隔天標籤開始。

如果建置不會在一天內完成，這很有用。

--extra-submit <file>[;<file>]¶: 將額外的 .xml 部分檔案提交到儀表板。請參閱 ctest_submit() 命令的 PARTS ExtraFiles 選項。

--http-header <header>¶

版本 3.29 新增。

提交到儀表板時附加 HTTP 標頭。

此選項將使 CTest 在提交到儀表板時附加指定的標頭。此選項可以多次指定。

--http1.0¶

使用 HTTP 1.0 提交。

此選項將強制 CTest 使用 HTTP 1.0 將檔案提交到儀表板，而不是 HTTP 1.1。

--no-compress-output¶

提交時不壓縮測試輸出。

此標誌將關閉測試輸出的自動壓縮。使用此選項以保持與不支援壓縮測試輸出的舊版本 CDash 的相容性。

儀表板客戶端步驟 ¶

CTest 定義了一個排序的測試步驟列表，其中一些或全部可以作為儀表板客戶端運行

開始 (Start): 開始新的儀表板提交，它將由後續步驟記錄的結果組成。請參閱下面的 CTest 開始步驟區段。
更新 (Update): 從其版本控制儲存庫更新原始碼樹。記錄舊版本和新版本以及已更新的原始碼檔案列表。請參閱下面的 CTest 更新步驟區段。
配置 (Configure): 通過在建置樹中執行命令來配置軟體。記錄配置輸出日誌。請參閱下面的 CTest 配置步驟區段。
建置 (Build): 通過在建置樹中執行命令來建置軟體。記錄建置輸出日誌並檢測警告和錯誤。請參閱下面的 CTest 建置步驟區段。
測試 (Test): 通過從建置樹載入 CTestTestfile.cmake 並執行定義的測試來測試軟體。記錄每個測試的輸出和結果。請參閱下面的 CTest 測試步驟區段。
覆蓋率 (Coverage): 通過運行覆蓋率分析工具並記錄其輸出來計算原始碼的覆蓋率。請參閱下面的 CTest 覆蓋率步驟區段。
記憶體檢查 (MemCheck): 通過記憶體檢查工具運行軟體測試套件。記錄測試輸出、結果以及工具報告的問題。請參閱下面的 CTest 記憶體檢查步驟區段。
提交 (Submit): 將從其他測試步驟記錄的結果提交到軟體品質儀表板伺服器。請參閱下面的 CTest 提交步驟區段。

儀表板客戶端模式 ¶

CTest 定義了三種作為儀表板客戶端的操作模式

Nightly (每夜): 此模式旨在每天調用一次，通常在晚上。它預設啟用 Start、Update、Configure、Build、Test、Coverage 和 Submit 步驟。即使 Update 步驟報告原始碼樹沒有變更，選定的步驟也會運行。
Continuous (持續): 此模式旨在在整天重複調用。它預設啟用 Start、Update、Configure、Build、Test、Coverage 和 Submit 步驟，但如果在 Update 步驟報告原始碼樹沒有變更後，它會退出。
Experimental (實驗性): 此模式旨在由開發人員調用以測試本機變更。它預設啟用 Start、Configure、Build、Test、Coverage 和 Submit 步驟。

通過 CTest 命令行使用儀表板客戶端 ¶

CTest 可以在已產生的建置樹上執行測試。運行 ctest 命令，並將當前工作目錄設定為建置樹，並使用以下簽名之一

ctest -D <mode>[<step>]
ctest -M <mode> [-T <step>]...

<mode> 必須是上述儀表板客戶端模式之一，並且每個 <step> 必須是上述儀表板客戶端步驟之一。

CTest 從建置樹中名為 CTestConfiguration.ini 或 DartConfiguration.tcl（名稱是歷史遺留的）的檔案中讀取儀表板客戶端配置設定。檔案的格式為

# Lines starting in '#' are comments.
# Other non-blank lines are key-value pairs.
<setting>: <value>

其中 <setting> 是設定名稱，<value> 是設定值。

在由 CMake 產生的建置樹中，如果專案包含 CTest 模組，則此組態檔案由該模組產生。該模組使用變數來獲取每個設定的值，如下面的設定文件所述。

通過 CTest 腳本使用儀表板客戶端 ¶

CTest 可以通過 cmake-language(7) 腳本驅動執行測試，該腳本建立和維護原始碼和建置樹，以及執行測試步驟。運行 ctest 命令，並將當前工作目錄設定在任何建置樹之外，並使用以下簽名之一

ctest -S <script>
ctest -SP <script>

<script> 檔案必須調用 CTest 命令命令來顯式運行測試步驟，如下文所述。這些命令從其參數或腳本中設定的變數中獲取儀表板客戶端配置設定。

儀表板客戶端配置 ¶

儀表板客戶端步驟可以通過命名設定進行配置，如下面的章節中所述。

CTest 開始步驟 ¶

開始新的儀表板提交，它將由後續步驟記錄的結果組成。

在 CTest 腳本中，ctest_start() 命令運行此步驟。命令的參數可以指定某些步驟設定。該命令首先運行由 CTEST_CHECKOUT_COMMAND 變數（如果已設定）指定的命令行，以初始化原始碼目錄。

組態設定包括

BuildDirectory (建置目錄)

專案建置樹的完整路徑。

CTest 腳本變數： CTEST_BINARY_DIRECTORY
CTest 模組變數： PROJECT_BINARY_DIR

SourceDirectory (原始碼目錄)

專案原始碼樹的完整路徑。

CTest 腳本變數： CTEST_SOURCE_DIRECTORY
CTest 模組變數： PROJECT_SOURCE_DIR

CTest 更新步驟 ¶

在 CTest 腳本中，ctest_update() 命令運行此步驟。命令的參數可以指定某些步驟設定。

用於指定版本控制工具的組態設定包括

BZRCommand

如果原始碼樹由 Bazaar 管理，則要使用的 bzr 命令行工具。

CTest 腳本變數： CTEST_BZR_COMMAND
CTest 模組變數：無

BZRUpdateOptions

更新原始碼時 BZRCommand 的命令行選項。

CTest 腳本變數： CTEST_BZR_UPDATE_OPTIONS
CTest 模組變數：無

CVSCommand

如果原始碼樹由 CVS 管理，則要使用的 cvs 命令行工具。

CTest 腳本變數： CTEST_CVS_COMMAND
CTest 模組變數： CVSCOMMAND

CVSUpdateOptions

更新原始碼時 CVSCommand 的命令行選項。

CTest 腳本變數： CTEST_CVS_UPDATE_OPTIONS
CTest 模組變數： CVS_UPDATE_OPTIONS

GITCommand

如果原始碼樹由 Git 管理，則要使用的 git 命令行工具。

CTest 腳本變數： CTEST_GIT_COMMAND
CTest 模組變數： GITCOMMAND

原始碼樹通過 git fetch 更新，然後通過 git reset --hard 重置為 FETCH_HEAD。結果與 git pull 相同，只是任何本機修改都會被覆蓋。使用 GITUpdateCustom 指定不同的方法。

GITInitSubmodules

如果設定，CTest 將在更新之前更新儲存庫的子模組。

CTest 腳本變數： CTEST_GIT_INIT_SUBMODULES
CTest 模組變數： CTEST_GIT_INIT_SUBMODULES

GITUpdateCustom

指定要在原始碼樹（Git 工作樹）中運行的自訂命令行（作為分號分隔列表），以更新它，而不是運行 GITCommand。

CTest 腳本變數： CTEST_GIT_UPDATE_CUSTOM
CTest 模組變數： CTEST_GIT_UPDATE_CUSTOM

GITUpdateOptions

更新原始碼時 GITCommand 的命令行選項。

CTest 腳本變數： CTEST_GIT_UPDATE_OPTIONS
CTest 模組變數： GIT_UPDATE_OPTIONS

HGCommand

如果原始碼樹由 Mercurial 管理，則要使用的 hg 命令行工具。

CTest 腳本變數： CTEST_HG_COMMAND
CTest 模組變數：無

HGUpdateOptions

更新原始碼時 HGCommand 的命令行選項。

CTest 腳本變數： CTEST_HG_UPDATE_OPTIONS
CTest 模組變數：無

P4Client

P4Command 的 -c 選項的值。

CTest 腳本變數： CTEST_P4_CLIENT
CTest 模組變數： CTEST_P4_CLIENT

P4Command

如果原始碼樹由 Perforce 管理，則要使用的 p4 命令行工具。

CTest 腳本變數： CTEST_P4_COMMAND
CTest 模組變數： P4COMMAND

P4Options

所有調用中 P4Command 的命令行選項。

CTest 腳本變數： CTEST_P4_OPTIONS
CTest 模組變數： CTEST_P4_OPTIONS

P4UpdateCustom

指定要在原始碼樹（Perforce 樹）中運行的自訂命令行（作為分號分隔列表），以更新它，而不是運行 P4Command。

CTest 腳本變數：無
CTest 模組變數： CTEST_P4_UPDATE_CUSTOM

P4UpdateOptions

更新原始碼時 P4Command 的命令行選項。

CTest 腳本變數： CTEST_P4_UPDATE_OPTIONS
CTest 模組變數： CTEST_P4_UPDATE_OPTIONS

SVNCommand

如果原始碼樹由 Subversion 管理，則要使用的 svn 命令行工具。

CTest 腳本變數： CTEST_SVN_COMMAND
CTest 模組變數： SVNCOMMAND

SVNOptions

所有調用中 SVNCommand 的命令行選項。

CTest 腳本變數： CTEST_SVN_OPTIONS
CTest 模組變數： CTEST_SVN_OPTIONS

SVNUpdateOptions

更新原始碼時 SVNCommand 的命令行選項。

CTest 腳本變數： CTEST_SVN_UPDATE_OPTIONS
CTest 模組變數： SVN_UPDATE_OPTIONS

UpdateCommand

指定要使用的版本控制命令行工具，而無需檢測管理原始碼樹的 VCS。

CTest 腳本變數： CTEST_UPDATE_COMMAND
CTest 模組變數： <VCS>COMMAND 當 UPDATE_TYPE 為 <vcs> 時，否則為 UPDATE_COMMAND

UpdateOptions

用於 UpdateCommand 的命令列選項。

CTest 腳本變數： CTEST_UPDATE_OPTIONS
CTest 模組變數： <VCS>_UPDATE_OPTIONS 當 UPDATE_TYPE 為 <vcs> 時，否則為 UPDATE_OPTIONS

UpdateType

指定管理來源樹的版本控制系統（如果無法自動偵測）。值可以是 bzr、 cvs、 git、 hg、 p4 或 svn。

CTest 腳本變數：無，從來源樹偵測
CTest 模組變數： UPDATE_TYPE （如果已設定），否則為 CTEST_UPDATE_TYPE

UpdateVersionOnly

指定您希望版本控制更新命令僅發現目前已檢出的版本，而不是更新到不同的版本。

CTest 腳本變數： CTEST_UPDATE_VERSION_ONLY

UpdateVersionOverride

指定來源樹的目前版本。

當此變數設定為非空字串時，CTest 將報告您指定的值，而不是使用更新命令來發現目前已檢出的版本。使用此變數會取代 UpdateVersionOnly。與 UpdateVersionOnly 類似，使用此變數會告知 CTest 不要將來源樹更新到不同的版本。

CTest 腳本變數： CTEST_UPDATE_VERSION_OVERRIDE

其他組態設定包括

NightlyStartTime

在 Nightly 儀表板模式中，指定「每晚開始時間」。使用集中式版本控制系統 (cvs 和 svn)，Update 步驟會檢出截至此時間的軟體版本，以便多個用戶端選擇一個共同的版本進行測試。這在分散式版本控制系統中沒有明確定義，因此會忽略此設定。

CTest 腳本變數： CTEST_NIGHTLY_START_TIME
CTest 模組變數： NIGHTLY_START_TIME （如果已設定），否則為 CTEST_NIGHTLY_START_TIME

CTest 組態步驟 ¶

在 CTest 腳本中，ctest_configure() 命令會執行此步驟。命令的引數可以指定一些步驟設定。

組態設定包括

ConfigureCommand

啟動軟體組態程序的命令列。它將在 BuildDirectory 設定指定的位置執行。

CTest 腳本變數： CTEST_CONFIGURE_COMMAND
CTest 模組變數： CMAKE_COMMAND 後面接著 PROJECT_SOURCE_DIR

LabelsForSubprojects

指定以分號分隔的標籤清單，這些標籤將被視為子專案。當提交組態、測試或建置結果時，此對應將傳遞到 CDash。

CTest 腳本變數： CTEST_LABELS_FOR_SUBPROJECTS
CTest 模組變數： CTEST_LABELS_FOR_SUBPROJECTS

請參閱標籤與子專案摘要。

CTest 建置步驟 ¶

在 CTest 腳本中，ctest_build() 命令會執行此步驟。命令的引數可以指定一些步驟設定。

組態設定包括

DefaultCTestConfigurationType

當要啟動的建置系統允許在建置時選擇組態（例如 Debug、 Release）時，這會指定在未向 ctest 命令提供 -C 選項時要建置的預設組態。該值將替換 MakeCommand 的值，以取代其中出現的文字字串 ${CTEST_CONFIGURATION_TYPE}。

CTest 腳本變數： CTEST_CONFIGURATION_TYPE
CTest 模組變數： DEFAULT_CTEST_CONFIGURATION_TYPE，由 CMAKE_CONFIG_TYPE 環境變數初始化

LabelsForSubprojects

指定以分號分隔的標籤清單，這些標籤將被視為子專案。當提交組態、測試或建置結果時，此對應將傳遞到 CDash。

CTest 腳本變數： CTEST_LABELS_FOR_SUBPROJECTS
CTest 模組變數： CTEST_LABELS_FOR_SUBPROJECTS

請參閱標籤與子專案摘要。

MakeCommand

啟動軟體建置程序的命令列。它將在 BuildDirectory 設定指定的位置執行。

CTest 腳本變數： CTEST_BUILD_COMMAND
CTest 模組變數： MAKECOMMAND，由 build_command() 命令初始化

UseLaunchers

對於 CMake 使用 Makefile 產生器或 Ninja 產生器產生的建置樹，指定是否透過 CTestUseLaunchers 模組（也包含在 CTest 模組中）啟用 CTEST_USE_LAUNCHERS 功能。啟用後，產生的建置系統會使用「啟動器」封裝編譯器、連結器或自訂命令列的每次調用，「啟動器」透過環境變數和檔案與 CTest 通訊，以報告細化的建置警告和錯誤資訊。否則，CTest 必須「抓取」建置輸出日誌以取得診斷資訊。

CTest 腳本變數： CTEST_USE_LAUNCHERS
CTest 模組變數： CTEST_USE_LAUNCHERS

CTest 測試步驟 ¶

在 CTest 腳本中，ctest_test() 命令會執行此步驟。命令的引數可以指定一些步驟設定。

組態設定包括

ResourceSpecFile

指定資源規格檔案。

CTest 腳本變數： CTEST_RESOURCE_SPEC_FILE
CTest 模組變數： CTEST_RESOURCE_SPEC_FILE

有關更多資訊，請參閱資源分配。

LabelsForSubprojects

指定以分號分隔的標籤清單，這些標籤將被視為子專案。當提交組態、測試或建置結果時，此對應將傳遞到 CDash。

CTest 腳本變數： CTEST_LABELS_FOR_SUBPROJECTS
CTest 模組變數： CTEST_LABELS_FOR_SUBPROJECTS

請參閱標籤與子專案摘要。

TestLoad

在並行執行測試時 (例如使用 -j)，嘗試不要在測試可能導致 CPU 負載超過給定閾值時啟動測試。

CTest 腳本變數： CTEST_TEST_LOAD
CTest 模組變數： CTEST_TEST_LOAD

TimeOut

每個測試的預設逾時時間（如果未由 TIMEOUT 測試屬性或 --timeout 旗標指定）。

CTest 腳本變數： CTEST_TEST_TIMEOUT
CTest 模組變數： DART_TESTING_TIMEOUT

若要向 CDash 報告額外的測試值，請參閱額外測試量測。

CTest 涵蓋率步驟 ¶

在 CTest 腳本中，ctest_coverage() 命令會執行此步驟。命令的引數可以指定一些步驟設定。

組態設定包括

CoverageCommand

執行軟體涵蓋率分析的命令列工具。它將在 BuildDirectory 設定指定的位置執行。

CTest 腳本變數： CTEST_COVERAGE_COMMAND
CTest 模組變數： COVERAGE_COMMAND

CoverageExtraFlags

指定 CoverageCommand 工具的命令列選項。

CTest 腳本變數： CTEST_COVERAGE_EXTRA_FLAGS
CTest 模組變數： COVERAGE_EXTRA_FLAGS

這些選項是傳遞給 CoverageCommand 的第一個引數。

CTest 記憶體檢查步驟 ¶

在 CTest 腳本中，ctest_memcheck() 命令會執行此步驟。命令的引數可以指定一些步驟設定。

組態設定包括

MemoryCheckCommand

執行動態分析的命令列工具。測試命令列將透過此工具啟動。

CTest 腳本變數： CTEST_MEMORYCHECK_COMMAND
CTest 模組變數： MEMORYCHECK_COMMAND

MemoryCheckCommandOptions

指定 MemoryCheckCommand 工具的命令列選項。它們將放置在測試命令列之前。

CTest 腳本變數： CTEST_MEMORYCHECK_COMMAND_OPTIONS
CTest 模組變數： MEMORYCHECK_COMMAND_OPTIONS

MemoryCheckType

指定要執行的記憶體檢查類型。

CTest 腳本變數： CTEST_MEMORYCHECK_TYPE
CTest 模組變數： MEMORYCHECK_TYPE

MemoryCheckSanitizerOptions

指定在使用已啟用 Sanitizer 的建置執行時，Sanitizer 的選項。

CTest 腳本變數： CTEST_MEMORYCHECK_SANITIZER_OPTIONS
CTest 模組變數： MEMORYCHECK_SANITIZER_OPTIONS

MemoryCheckSuppressionFile

指定包含 MemoryCheckCommand 工具抑制規則的檔案。它將與工具適用的選項一起傳遞。

CTest 腳本變數： CTEST_MEMORYCHECK_SUPPRESSIONS_FILE
CTest 模組變數： MEMORYCHECK_SUPPRESSIONS_FILE

其他組態設定包括

BoundsCheckerCommand

指定一個 MemoryCheckCommand，已知其與 Bounds Checker 命令列相容。

CTest 腳本變數：無
CTest 模組變數：無

PurifyCommand

指定一個 MemoryCheckCommand，已知其與 Purify 命令列相容。

CTest 腳本變數：無
CTest 模組變數： PURIFYCOMMAND

ValgrindCommand

指定一個 MemoryCheckCommand，已知其與 Valgrind 命令列相容。

CTest 腳本變數：無
CTest 模組變數： VALGRIND_COMMAND

ValgrindCommandOptions

指定 ValgrindCommand 工具的命令列選項。它們將放置在測試命令列之前。

CTest 腳本變數：無
CTest 模組變數： VALGRIND_COMMAND_OPTIONS

DrMemoryCommand

指定一個 MemoryCheckCommand，已知其與 DrMemory 命令列相容。

CTest 腳本變數：無
CTest 模組變數： DRMEMORY_COMMAND

DrMemoryCommandOptions

指定 DrMemoryCommand 工具的命令列選項。它們將放置在測試命令列之前。

CTest 腳本變數：無
CTest 模組變數： DRMEMORY_COMMAND_OPTIONS

CudaSanitizerCommand

指定一個 MemoryCheckCommand，已知其與 cuda-memcheck 或 compute-sanitizer 命令列相容。

CTest 腳本變數：無
CTest 模組變數： CUDA_SANITIZER_COMMAND

CudaSanitizerCommandOptions

指定 CudaSanitizerCommand 工具的命令列選項。它們將放置在測試命令列之前。

CTest 腳本變數：無
CTest 模組變數： CUDA_SANITIZER_COMMAND_OPTIONS

CTest 提交步驟 ¶

在 CTest 腳本中，ctest_submit() 命令會執行此步驟。命令的引數可以指定一些步驟設定。

組態設定包括

BuildName

用簡短的字串描述儀表板用戶端平台。（作業系統、編譯器等）

CTest 腳本變數： CTEST_BUILD_NAME
CTest 模組變數： BUILDNAME

CDashVersion

舊版選項。未使用。

CTest 腳本變數：無，從伺服器偵測
CTest 模組變數： CTEST_CDASH_VERSION

CTestSubmitRetryCount

指定在網路失敗時重試提交的嘗試次數。

CTest 腳本變數：無，使用 ctest_submit() RETRY_COUNT 選項。
CTest 模組變數： CTEST_SUBMIT_RETRY_COUNT

CTestSubmitRetryDelay

指定在網路失敗時重試提交之前的延遲時間。

CTest 腳本變數：無，使用 ctest_submit() RETRY_DELAY 選項。
CTest 模組變數： CTEST_SUBMIT_RETRY_DELAY

CurlOptions

版本 3.30 中已棄用：改用 TLSVerify。

指定以分號分隔的選項清單，以控制 CTest 內部用來連線到伺服器的 Curl 程式庫。

CTest 腳本變數： CTEST_CURL_OPTIONS
CTest 模組變數： CTEST_CURL_OPTIONS

可能的選項有

CURLOPT_SSL_VERIFYPEER_OFF: 停用 CURLOPT_SSL_VERIFYPEER curl 選項。
CURLOPT_SSL_VERIFYHOST_OFF: 停用 CURLOPT_SSL_VERIFYHOST curl 選項。

DropLocation