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=<預設值>¶: 使用測試預設值來指定測試選項。專案二進位目錄是從 configurePreset 鍵推斷的。目前的工作目錄必須包含 CMake 預設檔案。請參閱 預設值 以取得更多詳細資訊。

--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 [<層級>], --parallel [<層級>]¶

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

在 3.29 版本中新增：可以省略 <層級> 或 0，在這種情況下

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

也可以透過 CTEST_PARALLEL_LEVEL 環境變數來指定此選項。

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

--resource-spec-file <檔案>¶

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

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

--test-load <層級>¶

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

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

-Q, --quiet¶

讓 CTest 靜音。

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

-O <檔案>, --output-log <檔案>¶

輸出到日誌檔。

此選項會指示 CTest 將其所有輸出寫入 <檔案> 日誌檔。

--output-junit <檔案>¶

於 3.21 版本新增。

以 JUnit 格式寫入測試結果。

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

-N, --show-only[=<格式>]¶

停用實際執行測試。

此選項會指示 CTest 列出將要執行的測試，但實際上不執行它們。與 -R 和 -E 選項一起使用時很有用。

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

<格式> 可以是下列其中一個值。

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

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

-L <正規表示式>, --label-regex <正規表示式>¶

執行標籤與 string(REGEX) 中所述的正規表示式相符的測試。

此選項會指示 CTest 僅執行標籤與給定正規表示式相符的測試。當給定多個 -L 選項時，只有在每個正規表示式都與測試的至少一個標籤相符時，才會執行測試（即多個 -L 標籤形成 AND 關係）。請參閱標籤比對。

-R <正規表示式>, --tests-regex <正規表示式>¶

執行與正規表示式相符的測試。

此選項會指示 CTest 僅執行名稱與給定正規表示式相符的測試。

-E <正規表示式>, --exclude-regex <正規表示式>¶

排除與正規表示式相符的測試。

此選項會指示 CTest 不要執行名稱與給定正規表示式相符的測試。

-LE <正規表示式>, --label-exclude <正規表示式>¶

排除標籤與正規表示式相符的測試。

此選項會指示 CTest 不要執行標籤與給定正規表示式相符的測試。當給定多個 -LE 選項時，只有在每個正規表示式都與測試的至少一個標籤相符時，才會排除測試（即多個 -LE 標籤形成 AND 關係）。請參閱標籤比對。

--tests-from-file <檔案名稱>¶

於 3.29 版本新增。

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

此選項會指示 CTest 執行給定檔案中列出的測試。該檔案每行必須包含一個確切的測試名稱。不完全符合任何測試名稱的行將被忽略。此選項可以與其他選項（如 -R、-E、-L 或 -LE）組合使用。

--exclude-from-file <檔案名稱>¶

於 3.29 版本新增。

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

此選項會指示 CTest 不要執行給定檔案中列出的測試。該檔案每行必須包含一個確切的測試名稱。不完全符合任何測試名稱的行將被忽略。此選項可以與其他選項（如 -R、-E、-L 或 -LE）組合使用。

-FA <正規表示式>, --fixture-exclude-any <正規表示式>¶

從自動將任何測試新增到測試集中，排除與 <正規表示式> 相符的 fixture。

如果待執行的測試集中的某個測試需要特定的 fixture，則該 fixture 的設定和清除測試通常會自動新增到測試集中。此選項可防止新增與 <正規表示式> 相符的 fixture 的設定或清除測試。請注意，會保留所有其他 fixture 行為，包括測試相依性和跳過 fixture 設定測試失敗的測試。

-FS <正規表示式>, --fixture-exclude-setup <正規表示式>¶: 與 -FA 相同，但僅排除相符的設定測試。

-FC <正規表示式>, --fixture-exclude-cleanup <正規表示式>¶: 與 -FA 相同，但僅排除相符的清除測試。

-I [開始,結束,步幅,測試#,測試#|測試檔案], --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。

在 CMake 3.11 之前，Windows 上的互動模式允許顯示系統偵錯彈出視窗。現在，由於 CTest 使用 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 執行個體作為新的程序執行。

預設情況下，CTest 會在同一個程序中執行子 CTest 執行個體。如果不需要此行為，則此引數會強制子 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>]¶

列印一個命令的說明並結束。

以人類可讀的文字格式列印 <cmd> 的 cmake-commands(7) 手冊條目。如果指定了 <file>，則輸出將列印到該檔案。

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

列出可取得說明的命令並結束。

該清單包含所有可使用 --help-command 選項後跟命令名稱來取得說明的命令。如果指定了 <file>，則輸出將列印到該檔案。

--help-commands [<file>]¶

列印 cmake-commands 手冊並結束。

以人類可讀的文字格式列印 cmake-commands(7) 手冊。如果指定了 <file>，則輸出將列印到該檔案。

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

列印一個模組的說明並結束。

以人類可讀的文字格式列印 <mod> 的 cmake-modules(7) 手冊條目。如果指定了 <file>，則輸出將列印到該檔案。

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

列出可取得說明的模組並結束。

該清單包含所有可使用 --help-module 選項後跟模組名稱來取得說明的模組。如果指定了 <file>，則輸出將列印到該檔案。

--help-modules [<file>]¶

列印 cmake-modules 手冊並結束。

以人類可讀的文字格式列印 cmake-modules(7) 手冊。如果指定了 <file>，則輸出將列印到該檔案。

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

列印一個政策的說明並結束。

以人類可讀的文字格式列印 <cmp> 的 cmake-policies(7) 手冊條目。如果指定了 <file>，則輸出將列印到該檔案。

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

列出可取得說明的政策並結束。

該清單包含所有可使用 --help-policy 選項後跟政策名稱來取得說明的政策。如果指定了 <file>，則輸出將列印到該檔案。

--help-policies [<file>]¶

列印 cmake-policies 手冊並結束。

以人類可讀的文字格式列印 cmake-policies(7) 手冊。如果指定了 <file>，則輸出將列印到該檔案。

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

列印一個屬性的說明並結束。

以人類可讀的文字格式列印 <prop> 的 cmake-properties(7) 手冊條目。如果指定了 <file>，則輸出將列印到該檔案。

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

列出可取得說明的屬性並結束。

該清單包含所有可使用 --help-property 選項後跟屬性名稱來取得說明的屬性。如果指定了 <file>，則輸出將列印到該檔案。

--help-properties [<file>]¶

列印 cmake-properties 手冊並結束。

以人類可讀的文字格式列印 cmake-properties(7) 手冊。如果指定了 <file>，則輸出將列印到該檔案。

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

列印一個變數的說明並結束。

以人類可讀的文字格式印出 <var> 的 cmake-variables(7) 手冊條目。如果指定了名稱為 <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 將會在標籤和子專案摘要中顯示加權測試時間結果。時間會以秒*處理器而不是僅僅秒來報告。

針對每個標籤或子專案 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]：針對 j 標籤或子專案之 i 測試的 CTest PROCESSORS 屬性值
num_tests[j]：與 j 標籤或子專案相關聯的測試數目
total：至少執行一個測試的標籤或子專案總數

因此，每個標籤或子專案的加權時間摘要代表 CTest 為執行每個標籤或子專案的測試所分配的時間量，並且可以很好地表示每個標籤或子專案的測試總成本與其他標籤或子專案相比的總成本。

例如，如果 SubprojectA 顯示 100 秒*處理器，而 SubprojectB 顯示 10 秒*處理器，則 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-and-test 必須提供 --build-generator 選項。如果指定了 --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 客戶端並執行儀表板測試。所有測試都是 <模式><測試>，其中 <模式> 可以是 Experimental、Nightly 和 Continuous，而 <測試> 可以是 Start、Update、Configure、Build、Test、Coverage 和 Submit。

如果 <dashboard> 不是已識別的 <Mode><Test> 值之一，則會將其視為變數定義（請參閱下方的 dashboard-options）。

-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>]¶

將額外的檔案提交至儀表板。

此選項會將額外的檔案提交至儀表板。

--http-header <header>¶

於 3.29 版本新增。

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

此選項會導致 CTest 在提交至儀表板時附加指定的標頭。此選項可以多次指定。

--http1.0¶

使用 HTTP 1.0 提交。

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

--no-compress-output¶

提交時不壓縮測試輸出。

此旗標會關閉測試輸出的自動壓縮。使用此旗標以維持與不支援壓縮測試輸出的舊版 CDash 的相容性。

儀表板客戶端步驟 ¶

CTest 定義了測試步驟的排序清單，其中部分或全部步驟可以作為儀表板客戶端執行

開始: 開始新的儀表板提交，其中包含由下列步驟記錄的結果。請參閱下方的 CTest 開始步驟章節。
更新: 從其版本控制儲存庫更新來源樹狀結構。記錄舊版和新版以及更新的來源檔案清單。請參閱下方的 CTest 更新步驟章節。
設定: 透過在建置樹中執行命令來設定軟體。記錄設定輸出的日誌。請參閱下方的CTest 設定步驟章節。
建置: 透過在建置樹中執行命令來建置軟體。記錄建置輸出的日誌並偵測警告和錯誤。請參閱下方的CTest 建置步驟章節。
測試: 透過從建置樹載入 CTestTestfile.cmake 並執行定義的測試來測試軟體。記錄每個測試的輸出和結果。請參閱下方的CTest 測試步驟章節。
覆蓋率: 透過執行覆蓋率分析工具並記錄其輸出，計算原始碼的覆蓋率。請參閱下方的CTest 覆蓋率步驟章節。
記憶體檢查: 透過記憶體檢查工具執行軟體測試套件。記錄測試輸出、結果和工具回報的問題。請參閱下方的CTest 記憶體檢查步驟章節。
提交: 將從其他測試步驟記錄的結果提交到軟體品質儀表板伺服器。請參閱下方的CTest 提交步驟章節。

儀表板客戶端模式 ¶

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

夜間: 此模式旨在每天調用一次，通常在夜間。它預設啟用 Start、 Update、 Configure、 Build、 Test、 Coverage 和 Submit 步驟。即使 Update 步驟回報原始碼樹沒有變更，選定的步驟也會執行。
持續: 此模式旨在全天重複調用。它預設啟用 Start、 Update、 Configure、 Build、 Test、 Coverage 和 Submit 步驟，但如果 Update 步驟回報原始碼樹沒有變更，則在該步驟後退出。
實驗性: 此模式旨在由開發人員調用以測試本機變更。它預設啟用 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 模組變數：當 UPDATE_TYPE 為 <vcs> 時為 <VCS>COMMAND，否則為 UPDATE_COMMAND

UpdateOptions

UpdateCommand 的命令列選項。

CTest 腳本變數：CTEST_UPDATE_OPTIONS
CTest 模組變數：當 UPDATE_TYPE 為 <vcs> 時為 <VCS>_UPDATE_OPTIONS，否則為 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

在使用已啟用清理程式的版本執行時，指定清理程式的選項。

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

MemoryCheckSuppressionFile

指定一個包含 MemoryCheckCommand 工具的抑制規則的檔案。它將透過適用於該工具的選項傳遞。

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

其他組態設定包括

BoundsCheckerCommand

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

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

PurifyCommand

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

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

ValgrindCommand

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

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

ValgrindCommandOptions

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

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

DrMemoryCommand

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

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

DrMemoryCommandOptions

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

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

CudaSanitizerCommand

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

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